Skip to main content

Chats

Chats are named, persistent conversation containers scoped to the authenticated user. Each chat is associated with an agent and a memory strategy. Users can only access their own chats.

Chat object​

{
  "id": "01HXZ...",
  "agent_id": "researcher",
  "user_id": "01HYA...",
  "title": "Paris research",
  "label": "travel",
  "memory_strategy": "overflow",
  "compressor": null,
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

Memory strategies:

  • plain — unlimited raw history
  • overflow — truncates when context window is exceeded
  • compression — compresses old turns via LLM summary

POST /v1/chats​

Create a chat.

Request

{
  "agent_id": "researcher",
  "title": "Paris research",
  "label": "travel",
  "memory_strategy": "overflow"
}

agent_id is required. The agent must exist. memory_strategy defaults to plain.

Response 201 — chat object.

GET /v1/chats​

List chats for the authenticated user.

Query params

  • agent_id — filter by agent
  • label — substring filter on label
curl http://localhost:8080/v1/chats?label=travel \
  -H "Authorization: Bearer $ACCESS" | jq .

GET /v1/chats/{id}​

Get a single chat. Returns 403 if the chat belongs to another user.

PATCH /v1/chats/{id}​

Update title and/or label. Partial update — omit fields to leave unchanged.

{
  "title": "Updated title",
  "label": "work"
}

Response 200 — updated chat object.

Returns 403 if the chat belongs to another user.

DELETE /v1/chats/{id}​

Delete a chat. Returns 204. Returns 403 if the chat belongs to another user.

curl examples​

# Create
curl -s -X POST http://localhost:8080/v1/chats \
  -H "Authorization: Bearer $ACCESS" \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"researcher","title":"My research","memory_strategy":"overflow"}' | jq .

# List by label
curl -s "http://localhost:8080/v1/chats?label=travel" \
  -H "Authorization: Bearer $ACCESS" | jq .

# Update
CHAT_ID=01HXZ...
curl -s -X PATCH "http://localhost:8080/v1/chats/$CHAT_ID" \
  -H "Authorization: Bearer $ACCESS" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Renamed"}' | jq .

# Delete
curl -s -X DELETE "http://localhost:8080/v1/chats/$CHAT_ID" \
  -H "Authorization: Bearer $ACCESS"