Ask a question and receive a cited answer.
POST /queries
curl -X POST https://api.brewmycode.com/v1/queries \
-H "Authorization: Bearer $BMC_API_KEY" -H "Content-Type: application/json" \
-d '{
"knowledge_base": "ops-eu",
"query": "Which suppliers have open August invoices, and who approved them?",
"as_user": "marja@example.com",
"conversation": null,
"options": { "max_citations": 6, "language": "auto", "include_retrieval": false }
}'
| Field | Type | Notes |
|---|---|---|
knowledge_base | string or string[] | Name or id; omit to use all knowledge bases the user can access |
query | string | The question |
as_user | string | Workspace user email; permissions are filtered for this user |
conversation | string | Optional conversation id to keep context |
options.max_citations | int | Default 8 |
options.language | string | auto (language of the question) or a BCP-47 tag |
options.include_retrieval | bool | Include all retrieved passages, not only cited ones |
options.min_confidence | number | Decline below this instead of caveating |
{
"id": "qry_01j9x3k2m7",
"answer": "Three suppliers have open August invoices totalling €18,420 … [1][2]",
"confidence": 0.91,
"citations": [
{
"n": 1,
"document_id": "doc_01j9…",
"document": "invoices-2026-08.xlsx",
"source": "google_drive",
"url": "https://docs.google.com/spreadsheets/d/…#gid=0&range=B14:F16",
"excerpt": "Nordic Print Oy · 2026-08-14 · 6 240,00 …"
}
],
"knowledge_bases": ["kb_01j9x3k2m7"],
"conversation": "conv_01j9x…",
"as_user": "marja@example.com",
"latency_ms": 1840,
"created_at": "2026-09-19T08:14:02Z"
}
Add "stream": true to receive server-sent events: token events with partial answer text, then citations, then done with the full object.
POST /queries/{id}/feedback with { "rating": "up" | "down", "comment": "…" }. Down-rated answers are routed to knowledge base editors and added to the evaluation set.
GET /queries/{id}/retrieval returns every passage considered with scores and the permission decision — useful for debugging.
GET /queries?knowledge_base=…&as_user=…&since=… (admin scope) lists logged queries.