3.0 KiB
Contract: Chat API
Base path: /api/v1/chat
Auth: HTTP Basic (shared credential) required on all endpoints.
POST /api/v1/chat/sessions
Create a new chat session, optionally tied to a topic.
Request body (application/json):
{
"topicId": "cerebral-aneurysm"
}
topicId is optional. If omitted, the session is free-form (any neurosurgery question).
Response 201 Created:
{
"sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"topicId": "cerebral-aneurysm",
"createdAt": "2026-03-31T10:20:00Z"
}
GET /api/v1/chat/sessions/{sessionId}/messages
Retrieve the full message history for a session, ordered chronologically.
Path param: sessionId — UUID
Response 200 OK:
[
{
"id": "msg-uuid-1",
"role": "USER",
"content": "What are the Hunt and Hess grading criteria?",
"createdAt": "2026-03-31T10:21:00Z"
},
{
"id": "msg-uuid-2",
"role": "ASSISTANT",
"content": "The Hunt and Hess scale grades subarachnoid haemorrhage severity...",
"sources": [
{ "bookTitle": "Principles of Neurosurgery", "page": 318 }
],
"createdAt": "2026-03-31T10:21:04Z"
}
]
Response 404 Not Found:
{ "error": "Session not found." }
POST /api/v1/chat/sessions/{sessionId}/messages
Send a user message and receive an AI response grounded in uploaded books.
Path param: sessionId — UUID
Request body (application/json):
{
"content": "What are the Hunt and Hess grading criteria?"
}
Response 200 OK:
{
"id": "msg-uuid-2",
"role": "ASSISTANT",
"content": "The Hunt and Hess scale grades subarachnoid haemorrhage severity on a scale of I–V...",
"sources": [
{ "bookTitle": "Principles of Neurosurgery", "page": 318 }
],
"createdAt": "2026-03-31T10:21:04Z"
}
When no source found — response still 200 OK, but sources is empty and content explicitly states the limitation:
{
"id": "msg-uuid-3",
"role": "ASSISTANT",
"content": "I could not find relevant information about this topic in the uploaded books.",
"sources": [],
"createdAt": "2026-03-31T10:22:00Z"
}
Response 404 Not Found:
{ "error": "Session not found." }
Response 503 Service Unavailable (no READY books):
{ "error": "No books are available as knowledge sources." }
DELETE /api/v1/chat/sessions/{sessionId}
Delete a session and all its messages (clear conversation history).
Response 204 No Content: Session deleted.
Response 404 Not Found:
{ "error": "Session not found." }
Notes
- Responses are synchronous for the POC; no streaming or SSE required at this stage.
- The backend includes the full conversation history (all prior messages in the session) in the LLM context window to maintain multi-turn coherence.
- The AI is instructed via system prompt to answer only from retrieved book chunks and to explicitly state when no relevant context was found.