Skip to content

Ask a question

Run the retrieval and reasoning pipeline, and read the answer with its sources.

One endpoint runs the whole pipeline: it plans the retrieval, searches the corpora, reasons over what it found, and validates the answer against its sources before returning.

POST/api/v1/chat

Request

query
stringRequired
The question, 1 to 2000 characters. Natural language; no special syntax.
conversation_id
integer | null
Omit to start a new thread. Pass the id you got back to continue one with full multi-turn context.
end_user_id
string= default
Up to 128 characters. Your own identifier for the person asking. Threads are isolated per (API key, end_user_id), so leaving this at the default puts every user in one shared thread.
curl -X POST "https://api-seerahai.karmat-hq.com/api/v1/chat" \
  -H "X-API-Key: $SEERAH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What does the Quran say about patience?",
    "end_user_id": "user-8842"
  }'

Retrieval takes time

A single call plans, searches four corpora and reasons over the results. Set a generous client timeout (60 seconds is sensible) and show the user a waiting state rather than failing at 10.

Response

json
{
  "answer": "Patience (sabr) is among the most frequently commended qualities in the Quran...",
  "sources": [
    {
      "corpus": "quran",
      "reference": "Al-Baqarah 2:153",
      "text": "O you who have believed, seek help through patience and prayer...",
      "score": 0.91
    },
    {
      "corpus": "hadith",
      "reference": "Sahih al-Bukhari 1469",
      "text": "...and whoever remains patient, Allah will make him patient...",
      "score": 0.86
    }
  ],
  "sources_found": 7,
  "conversation_id": 4182,
  "plan": { "strategy": "multi_corpus", "corpora": ["quran", "hadith"] },
  "validation": { "grounded": true, "unsupported_claims": [] },
  "run_id": "run_01HQB7Y4K2",
  "end_user_id": "user-8842"
}
answer
string
The composed answer. Render this as the response.
sources
object[]
The passages the answer was built from, with their references. Show these: an unverifiable religious answer is worse than no answer.
sources_found
integer
How many passages the retrieval matched in total. A low number on a confident answer is a signal worth surfacing to yourself in logs.
conversation_id
integer
The thread. Pass it back on the next question to keep context.
plan
object
How the pipeline decided to search. Useful when debugging why a question retrieved the wrong material.
validation
object
The self-check against retrieved sources. Log this. It is the field that tells you when an answer drifted beyond what it could support.
run_id
string
Handle for this specific execution. Send it to us with any report of a bad answer.
end_user_id
string
Echoed back, so you can assert it matched.

Always display the sources

This is religious material, and people act on it. Render the references alongside the answer and make them the visible part of the design, not a collapsed footnote. Where validation.grounded is false, say so rather than presenting the answer as settled.

Multi-turn behaviour

Omitting conversation_id starts a fresh thread and returns a new one. Passing it continues that thread with the full prior context, so follow-ups like “and in the Hadith?” resolve correctly against the previous question.

Threads persist. Use the conversation endpoints to list and read them back, and to delete on your own retention schedule.

Errors

401
unauthorized
Invalid, revoked or expired key.
403
forbidden
Role or scope insufficient for this endpoint.
422
validation_error
Usually an empty query, or one over 2000 characters.
429
rate_limited
Over your key's per-minute limit. Read Retry-After and the X-RateLimit-* headers; your ceiling is reported by GET /api/v1/status.