Chat API

POST /api/v1/gateway/chat asks Qry a question and returns the whole answer in one JSON response. It runs through the same pipeline as the web: the same models, skills, tools and — because every token belongs to exactly one person — the same permissions, row filters included. The Telegram integration is built on it.

Authentication

Send a token as a bearer header. Each one identifies one person; none of them lets the caller choose a different user.

Token	Prefix	Created in
Messaging token	qry_msg_	Settings → Messaging channels — for Telegram, WhatsApp or your own adapter
CLI token	qry_cli_	qry login (see the operator CLI)
API key	qry_	an API client in Nexus; it acts as the person who owns it

Requests are rate-limited per token (30 a minute by default).

Request

curl https://qry.your-company.com/api/v1/gateway/chat \
  -H "Authorization: Bearer $QRY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Sales by region last quarter, compared with the one before",
    "datasource_id": "<datasource id>",
    "catalog": "<catalog>",
    "schema": "<schema>"
  }'

Field	Required	Meaning
message	yes	The question, up to 8,000 characters.
conversation_id	no	Continue an existing conversation instead of starting one.
workspace_id	no	Ask inside a workspace — its documents, instructions and memory. Membership is checked.
datasource_id, catalog, schema	no	The data to ask about, as in the Catalog.
model, service	no	A specific model; the deployment's default otherwise.
chat_id	no	Your own id for the request, needed to cancel it while it runs.
timeout_seconds	no	10 to 300; 90 by default.

Response

{
  "chat_id": "c2f1…",
  "conversation_id": "8a07…",
  "text": "Sales grew 6.4% quarter on quarter. North led with…",
  "attachments": [
    { "type": "dataset", "row_count": 4, "data_ref": "…" }
  ],
  "tool_calls": 2,
  "elapsed_seconds": 7.9,
  "truncated": false,
  "error": null
}

• text — the answer, in Markdown.
• attachments — what the answer produced: dataset (a result set, by reference, with its row count), image or file (inline, base64, up to a size limit; larger ones are marked oversized).
• conversation_id — pass it back to continue the conversation.
• provenance_warning — present only when a figure in the answer does not appear in the data Qry read. Show it next to the text; do not drop it.
• error — set when the model or a tool failed; the HTTP status is 502 when the run produced no answer at all.

Notes

• One call waits for the whole answer; there is no streaming on this endpoint.
• Every call is recorded in the deployment's audit of messaging requests (who, when, how long — not the content).