API summary

A compact reference for the versioned API. Base URL: http://127.0.0.1:8000.

Audience: developers integrating against the API. What you will accomplish: find the right endpoint and know which headers to set and log.

Endpoints

Method & path	Purpose
`POST /api/v1/chat`	Ask a question; returns `{ answer, sources[], meta }`. See Chatting.
`POST /api/v1/chat/stream`	Same body, streamed as SSE. See Streaming.
`POST /api/v1/ingest`	Ingest from a remote URL → `202` + `Location`. See Ingestion.
`POST /api/v1/ingest/upload`	Ingest an uploaded local file (multipart) → `202` + `Location`.
`GET /api/v1/ingest/status/{doc_id}`	Poll ingest status.
`GET /api/v1/ingest/docs?limit&cursor`	List ingested documents (paginated).
`DELETE /api/v1/ingest/{doc_id}`	Delete a document (always needs `X-API-Key`).
`GET /api/v1/review/pending?limit&cursor`	List synthesized answers awaiting review (API-key gated). See Review workflow.
`POST /api/v1/review/{entry_id}/approve`	Approve a synthesized answer → embed into the KB (API-key gated).
`POST /api/v1/review/{entry_id}/reject`	Reject a synthesized answer → discard (API-key gated).
`POST /api/v1/feedback`	Submit 👍/👎 feedback (open). See Rating answers.
`GET /api/v1/feedback?rating&limit&cursor`	List feedback (operator, API-key gated).
`GET /health`	Cached startup health: `ok` or `degraded`.
`GET /ready`	Live readiness probe: `200` ready, or `503` with dependency detail.

Request headers

Header	Purpose	Required?
`X-User-Id`	Scopes conversation memory. Allowed: `[A-Za-z0-9_.@-]`, ≤128 chars.	Optional (defaults to `anonymous`).
`X-API-Key`	Protects ingest management.	`DELETE` always; others when `REQUIRE_AUTH_FOR_INGEST=true`.
`Content-Type: application/json`	For JSON request bodies.	For chat/feedback/URL-ingest.

Response headers to log

Header	Why it matters
`X-Correlation-Id`	Trace a single request end-to-end; matches `meta.correlation_id`. Quote it in support requests.
`X-RateLimit-Limit`	Your per-window request budget.
`X-RateLimit-Remaining`	Requests left in the current window.
`X-RateLimit-Reset`	When the window resets (epoch seconds).
`Retry-After`	On `429`: seconds to wait before retrying.

Verify your result

Verify: Your client logs X-Correlation-Id from every response.
Verify: You read the X-RateLimit-* headers and back off on 429 per Retry-After.
Verify: You send a stable X-User-Id for memory and an X-API-Key where required.

Common mistakes and fixes

Using /api/* for new code → switch to /api/v1; the legacy paths are deprecated.
Not logging X-Correlation-Id → you lose the ability to trace issues; log it always.

Decode error responses in Errors & rate limits.
Understand X-User-Id scoping in Conversation memory.

Web client Configuration