Chat API

The chat endpoints are the most useful surface for automation: send a question, and the answer comes back grounded in whatever your pipelines have indexed — retrieval across all collections happens automatically on every message.

Start a conversation

curl -b cookies.txt -X POST $BASE/chats \
  -H 'Content-Type: application/json' \
  -d '{"model_name": "llama3.2", "message": "Summarize our vacation policy."}'

The response is the full conversation (ChatDetail):

{
  "id": "…chat uuid…",
  "title": "Vacation policy summary",
  "messages": [
    { "id": "…", "role": "user",      "content": "Summarize our vacation policy.", "model_name": "llama3.2", "tokens_used": 12, "sibling_index": 0, "sibling_count": 1, "created_at": "…" },
    { "id": "…", "role": "assistant", "content": "Employees accrue 1.5 days…",     "model_name": "llama3.2", "tokens_used": 148, "sibling_index": 0, "sibling_count": 1, "created_at": "…" }
  ],
  "created_at": "…",
  "updated_at": "…"
}

Things to know:

• The call blocks until the answer is fully generated — there is no streaming. Set your HTTP client’s timeout generously (large models can take a minute or more).
• model_name must be a model that exists in the organization, or you get 404 {"detail": "Model '…' not found"}.
• A short title is generated automatically from your first message.
• Retrieval is best-effort: if nothing relevant is indexed, the model answers from general knowledge — the shape of the response is identical.

Continue it

curl -b cookies.txt -X POST $BASE/chats/<chat_id>/followup \
  -H 'Content-Type: application/json' \
  -d '{"model_name": "llama3.2", "message": "And how many days roll over?"}'

Returns just the new [user, assistant] message pair. You can switch model_name on any message.

List, rename, delete

curl -b cookies.txt $BASE/chats                      # summaries: id, title, timestamps
curl -b cookies.txt -X POST $BASE/chats/<chat_id> \
  -H 'Content-Type: application/json' -d '{"new_title": "Policy Q&A"}'
curl -b cookies.txt -X DELETE $BASE/chats/<chat_id>  # permanent

Chats are private to the authenticated user.

Versions & branching

Conversations are trees: editing a user message or regenerating an assistant reply creates a sibling version rather than overwriting. Each message carries sibling_index / sibling_count so you can tell where alternatives exist.

# Re-answer an assistant message (adds a sibling)
curl -b cookies.txt -X POST $BASE/chats/<chat_id>/regenerate_response \
  -H 'Content-Type: application/json' \
  -d '{"assistant_message_id": "<message_id>", "model_name": "llama3.2"}'

# Edit a user message (new branch + fresh answer)
curl -b cookies.txt -X POST $BASE/chats/<chat_id>/edit_message \
  -H 'Content-Type: application/json' \
  -d '{"user_message_id": "<message_id>", "new_content": "…", "model_name": "llama3.2"}'

# Choose which sibling is active
curl -b cookies.txt -X POST $BASE/chats/<chat_id>/switch_branch \
  -H 'Content-Type: application/json' \
  -d '{"fk_message_id": "<parent_message_id>", "sibling_index": 1}'

# Read the currently active branch
curl -b cookies.txt $BASE/chats/<chat_id>/branch

All four return the full active-branch ChatDetail, so your client always has a consistent view after any mutation.