new_api_schema.md

AgreeUpon API v1 Schema

Base URL: /api/v1

Authentication /auth

Method	Path	Body	Success 200
POST	/auth/register	UserCreate	UserRead
POST	/auth/login	UserLogin	Token
POST	/auth/refresh	—	Token
POST	/auth/logout	—	{ok:true}

Conversations /conversations

Method	Path	Description	Success
POST	/conversations	create new conversation	Conversation
GET	/conversations	list conversations (limit,offset)	List[Conversation]
GET	/conversations/{id}	fetch single conversation	Conversation
DELETE	/conversations/{id}	delete conversation	204

Agent interaction (nested)

Method	Path	Body	Success
POST	/conversations/{id}/agent/message	MessageCreate	AgentReply
GET	/conversations/{id}/agent/stream?prompt=…	SSE	events: reply, document, done

Documents (nested)

Method	Path	Body	Success
GET	/conversations/{id}/document	—	Document
PUT	/conversations/{id}/document	DocumentUpdate	Document

Standard envelope

{
  "data": { … },          // null on error
  "error": {
    "code": "not_found",
    "message": "Conversation not found"
  }
}

Core Models (Python / Pydantic)

class UserCreate(BaseModel):
    username: constr(min_length=3, max_length=30)
    password: constr(min_length=8)

class Token(BaseModel):
    access_token: str
    token_type: str = "bearer"

class Conversation(BaseModel):
    id: int
    created_at: datetime

class MessageCreate(BaseModel):
    content: constr(min_length=1, max_length=10_000)

class AgentReply(BaseModel):
    assistant_reply: str
    document: Optional[str]

class Document(BaseModel):
    id: int
    conversation_id: int
    doc_type: Literal["contract", "memo", "unknown"]
    content: str
    updated_at: datetime

---

This schema is versioned, REST-ful, strongly typed, self-documenting, and prepared for expansion.