Answer a question from the knowledge base
Customer-facing grounded Answers API: take an end-user question, run hybrid knowledge-base retrieval plus a single grounded-answer LLM call, and return the answer with citations and a confidence score. Enforces per-document audience access control via audiences, and meters one billable resolution per answered query above the confidence floor. Each call is one LLM round-trip, so it counts against the AI spend cap. For raw ranked chunks without an answer, use POST /ai/kb/search instead.
Authorizations
Dashboard JWT token from Clerk
Headers
Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.
1 - 255Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
true, false Body
The end-user question to answer (1-2000 chars).
1 - 2000Optional knowledge-base allowlist. When present, retrieval is scoped to these KBs only; when omitted, the whole workspace knowledge base is searched. Max 20 ids.
201 - 120Max chunks retrieved to ground the answer (1-10). Defaults to 8.
1 <= x <= 10Optional retrieval similarity floor (0-1) passed through to the vector search.
0 <= x <= 1Confidence floor (0-1) above which an answer is charged as a billable resolution. Defaults to the platform bar (0.75); a lower-confidence answer is still returned but not billed.
0 <= x <= 1Optional language tag (e.g. en, pt-BR) — the answer is written in this language.
2 - 10The audience tokens (roles / segments) the end-user belongs to, used to enforce per-document access control. Omit / empty = anonymous requester → only unrestricted documents are eligible. Max 50.
501 - 120