Answers

Ask a question, get a grounded answer with its evidence and sources.

POST `/v1/chat`

Request

Field	Type	Required	Notes
`message`	string	Yes	The question. Up to 4000 characters. English or Arabic.
`mode`	string	No	`muslim` (default) or `dawah`. See Da'wah mode.
`background`	string	No	Only used in `dawah` mode: the reader's tradition, so the answer starts from where they stand.

curl https://api.rafiqai.app/v1/chat \
  -H "Authorization: Bearer $RAFIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Can I combine prayers while travelling?"
  }'

Response

{
  "answered": true,
  "mode": "muslim",
  "intent": "applied_fiqh",
  "answer": {
    "summary": "Yes — a traveller may combine Dhuhr with Asr, and Maghrib with Isha...",
    "detail": "The permission is established in the Sunnah...",
    "evidence": [
      { "heading": "From the Sunnah", "content": "..." }
    ],
    "note": "Scholars differ on the minimum distance..."
  },
  "sources": [
    { "referenceId": "...", "title": "...", "url": "..." }
  ],
  "usage": { "ms": 4820 }
}

Field	Meaning
`answered`	`false` when Rafiq found nothing in the corpus that answers the question. `answer.summary` then explains why, in language you can show the user directly.
`intent`	How the question was classified — useful for analytics and for routing in your own UI.
`answer.summary`	The answer in a sentence or two. If you display only one field, display this.
`answer.detail`	The full reasoning. May be several hundred words, in Markdown.
`answer.evidence`	Verses and narrations the answer rests on, already grouped under headings.
`answer.note`	Present when scholars genuinely differ, or when the answer carries a caveat. Do not drop this — it is often the part that keeps the answer honest.
`sources`	What was actually used. Showing these is strongly encouraged; it is how a reader checks Rafiq rather than trusting it.

Handle `answered: false`

It happens for out-of-scope questions ("what is the capital of Brazil"), for questions the corpus does not cover, and for questions that would require deriving a new ruling. Show answer.summary and let the user rephrase. Retrying the identical request will produce the identical outcome.

Latency

A chat call typically takes 3–20 seconds: it runs retrieval over a corpus of about 1.2 million documents and then generates prose. Set your client timeout to at least 60 seconds, and show a loading state. The reference endpoints below are far faster.