134 lines
3.0 KiB
Markdown
134 lines
3.0 KiB
Markdown
# 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`):
|
||
```json
|
||
{
|
||
"topicId": "cerebral-aneurysm"
|
||
}
|
||
```
|
||
`topicId` is optional. If omitted, the session is free-form (any neurosurgery question).
|
||
|
||
**Response 201 Created**:
|
||
```json
|
||
{
|
||
"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**:
|
||
```json
|
||
[
|
||
{
|
||
"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**:
|
||
```json
|
||
{ "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`):
|
||
```json
|
||
{
|
||
"content": "What are the Hunt and Hess grading criteria?"
|
||
}
|
||
```
|
||
|
||
**Response 200 OK**:
|
||
```json
|
||
{
|
||
"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:
|
||
```json
|
||
{
|
||
"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**:
|
||
```json
|
||
{ "error": "Session not found." }
|
||
```
|
||
|
||
**Response 503 Service Unavailable** (no READY books):
|
||
```json
|
||
{ "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**:
|
||
```json
|
||
{ "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.
|