projects/document_rag/data/samples/api_contract.md

API contract

These are project-authored demonstration notes for Document RAG Lab.

GET /health returns service status, chunk count, embedding model, and whether answer generation is configured. It does not return the API key or the local database path.

POST /ingest accepts up to eight documents in a batch. Each document has a source label and text. Labels must be unique within the batch. Uploading a newer version with the same source label replaces stale chunks for that source. The total index limit is 3,000 chunks.

POST /search accepts a question and retrieval settings. The candidate pool must be at least as large as top_k. The endpoint returns source excerpts, semantic and keyword scores, and measured search time.

POST /ask searches the index, packs the context, calls the configured model, and checks the numbered citations. GET /documents lists indexed source labels, chunk counts, and content hashes.

The API is a local educational service. Bind it to localhost. Authentication, access controls, rate limits, and a retention policy are required before a multi-user public deployment.