# 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.