Quickstart

Get a first grounded answer back from the chatbot in a few minutes.

Audience: developers integrating the HTTP API. What you will accomplish: send a question to POST /api/v1/chat and read the answer, its citations, and its grounding verdict. Estimated time: about 15 minutes.

Prerequisites

• A running server reachable at the base URL http://127.0.0.1:8000. (To start one, follow the project README: uvicorn main:app --reload, or docker-compose up --build.)
• At least one ingested document if you want a grounded answer in strict mode — see Ingesting documents. With no documents, strict mode will politely decline, which is expected behavior, not an error.
• curl (or any HTTP client).

Send your first question

1. 1

   Step 1: Confirm the server is up

   A healthy server responds to a health check. A degraded result means Redis or ChromaDB is unreachable — chat may still work, but retrieval can be impaired.

2. 2

   Step 2: Post a question to /api/v1/chat

   Send a stable X-User-Id so the bot can remember the conversation, and ask a question your documents can answer.

3. 3

   Step 3: Read the answer, sources, and grounding

   The response includes answer, structured sources[], and meta (including grounded and correlation_id). Quote the correlation_id if you ever need support.

1. Check health

curl http://127.0.0.1:8000/health

2. Ask a question

curl -X POST http://127.0.0.1:8000/api/v1/chat \
-H "Content-Type: application/json" \
-H "X-User-Id: alice" \
-d '{"q":"How long do I have to return an item?","mode":"strict","top_k":4}'

Expected result

A successful call returns JSON shaped like this:

{
  "answer": "You can return any item within 30 days of purchase.",
  "sources": [
    {
      "label": "return_policy.pdf",
      "doc_id": "return_policy",
      "score": 0.86,
      "page": 1,
      "snippet": "Customers may return any item within 30 days..."
    }
  ],
  "meta": {
    "mode": "strict",
    "lang": "en",
    "self_ingested": false,
    "grounded": "supported",
    "grounded_score": 0.86,
    "correlation_id": "b1f3…",
    "model": "gpt-4o-mini"
  }
}

Common failure modes

Related next steps

• Go deeper on the request body and modes in Chatting.
• Render a typing effect with Streaming (SSE).
• Add your own knowledge in Ingesting documents.