Chat API | DocuStore

Endpoints for conversational RAG with SSE streaming, conversation management, and message feedback.

The chat API provides a conversational RAG interface. Users ask questions and receive grounded, citation-backed answers streamed in real time via Server-Sent Events (SSE). Conversations are persisted in MongoDB for multi-turn continuity.

Create Conversation

POST /chat
Content-Type: application/json

{
  "title": "NadD inhibitor research"
}

Returns 201 Created with the conversation metadata:

{
  "conversation_id": "uuid",
  "workspace_id": "uuid",
  "owner_id": "uuid",
  "title": "NadD inhibitor research",
  "created_at": "2026-03-29T12:00:00Z",
  "is_archived": false
}

List Conversations

GET /chat?skip=0&limit=20&is_archived=false

Returns conversations for the current user, sorted by most recent activity.

Parameter	Type	Default	Description
`skip`	integer	`0`	Pagination offset
`limit`	integer	`20`	Max results
`is_archived`	boolean	`false`	Include archived conversations

Get Conversation

GET /chat/{conversation_id}?skip=0&limit=100

Returns the conversation with its message history. Messages are paginated.

Send Message (SSE Stream)

POST /chat/{conversation_id}/messages
Content-Type: application/json

{
  "message": "What are the most potent NadD inhibitors in our collection?",
  "mode": "thinking"
}

Field	Type	Required	Description
`message`	string	Yes	User message (1-10,000 characters)
`mode`	string	No	`quick`, `thinking`, or `deep_thinking`. Null uses server default.

Returns a text/event-stream response. The client should connect using an EventSource or SSE library.

SSE Event Types

Events are delivered as named SSE events with JSON data payloads:

`agent_step`

Emitted when a pipeline stage starts or completes. Includes optional thinking_content for stages that produce reasoning traces.

event: agent_step
data: {"type": "step_started", "step_name": "retrieval"}

event: agent_step
data: {"type": "step_completed", "step_name": "retrieval", "thinking_content": "Searched for NadD inhibitors, found 12 relevant sources", "thinking_label": "Search Iteration 1"}

`query_context`

Emitted after query planning with extracted entities and classification.

event: query_context
data: {"type": "query_context", "entities": ["NadD"], "authors": [], "query_type": "factual", "reformulated_query": "most potent NadD inhibitors"}

`retrieval_results`

Emitted after context assembly with the citation sources used for the answer.

event: retrieval_results
data: {"type": "retrieval_results", "citations": [{"index": 1, "page_id": "...", "artifact_title": "...", "chunk_text": "..."}]}

`token`

Streaming answer tokens. Emitted only during the answer formatting stage.

event: token
data: {"type": "token", "delta": "The most potent"}

event: token
data: {"type": "token", "delta": " NadD inhibitor in your collection is"}

`grounding_result`

Emitted after inline verification.

event: grounding_result
data: {"type": "grounding_result", "is_grounded": true, "confidence": 0.92}

`structured_block`

Rich content blocks such as tables or molecule renderings.

event: structured_block
data: {"type": "structured_block", "block_type": "table", "content": "..."}

`done`

Final event with metadata about the completed response.

event: done
data: {"type": "done", "message_id": "uuid", "total_tokens": 2340, "prompt_tokens": 1800, "completion_tokens": 540, "duration_ms": 8500, "sources": [...]}

`error`

Emitted if the pipeline encounters an error.

event: error
data: {"type": "error", "error_message": "Failed to connect to LLM provider"}

Client Example

const eventSource = new EventSource(
  `/chat/${conversationId}/messages`,
  { method: "POST", body: JSON.stringify({ message, mode: "thinking" }) }
);

eventSource.addEventListener("token", (e) => {
  const data = JSON.parse(e.data);
  appendToAnswer(data.delta);
});

eventSource.addEventListener("done", (e) => {
  const data = JSON.parse(e.data);
  setCitations(data.sources);
  eventSource.close();
});

Record Feedback

POST /chat/{conversation_id}/messages/{message_id}/feedback
Content-Type: application/json

{
  "feedback": "positive"
}

Returns 204 No Content. Records thumbs-up or thumbs-down feedback on a specific assistant message. Accepts "positive" or "negative".

Delete Conversation

DELETE /chat/{conversation_id}

Returns 204 No Content. Deletes the conversation and all its messages.