Conversation API
Stateful, context-aware multi-turn retrieval and synthesis.
Design Intent
The conversation API preserves context across turns so follow-up queries can be interpreted correctly without requiring client-side prompt stitching.
Example:
- "What is SVB?"
- "Why did it collapse?"
- "What was the federal response?"
Turn 2 and 3 are resolved using prior context.
Endpoints
Create conversation
Creates a new conversation object.
Endpoint: POST /conversations
List conversations
Endpoint: GET /conversations?page=1&page_size=20
Returns paginated conversation summaries.
Get conversation
Endpoint: GET /conversations/{id}
Returns the full conversation with messages and retrieval artifacts.
Add conversation message
Endpoint: POST /conversations/{id}/messages
Request body:
{
"query": "why did it collapse"
}Behavior:
- Uses recent prior queries to build retrieval context.
- Reranks using the current query intent.
- Synthesizes an answer with citations from top-ranked sources.
- Persists message + citations + selected retrieval results.
Delete conversation
Endpoint: DELETE /conversations/{id}
Deletes conversation state and returns 204.
Operational Notes
- Conversation storage is in-memory by default.
- Data resets on server restart unless persistence is added.
- For production, replace in-memory store with durable storage.