ai-teacher/specs/004-rag-retrieval-quality/contracts/chat-api.md

API Contract: Chat (unchanged endpoints)

Branch: 004-rag-retrieval-quality | Date: 2026-04-06

No endpoint changes

This feature makes no changes to the public API surface. All existing /api/v1/chat/... endpoints remain identical in path, method, request body, and response shape.

Message response — sources field addition

The only observable change to callers is that each source entry in Message.sources gains an optional refLabel field. This is backwards-compatible (additive only).

Existing contract (unchanged)

POST /api/v1/chat/sessions/{sessionId}/messages
Body: { "content": "..." }
Response: Message { id, sessionId, role, content, sources: [...], createdAt }

Source entry schema (additive change)

Before:

{ "type": "TEXT", "bookTitle": "...", "page": 142, "chunkText": "..." }

After (new optional field):

{ "type": "TEXT", "refLabel": "S1", "bookTitle": "...", "page": 142, "chunkText": "..." }

Frontend consumers that ignore unknown fields are unaffected. ChatMessage.vue may optionally use refLabel for future inline citation linking.