Gaur Docs

Reference for the OpenAI-compatible chat endpoint at POST /v1/api/{consumer_slug}/chat/completions.

Streams a natural-language answer over a consumer's contracts. The endpoint is OpenAI-compatible, with one important extension covered under The delta object. For a guided walkthrough, see Chat.

Request

POST /v1/api/{consumer_slug}/chat/completions
Authorization: Bearer <api_key>
Content-Type: application/json

Path parameters

Parameter	Type	Description
`consumer_slug`	string	The slug of the consumer. The API key must authorize this consumer, and the consumer must have the chat protocol enabled.

Body

Field	Type	Required	Description
`model`	string	Yes	The model identifier for the request.
`messages`	array	Yes	The conversation, oldest first.

Each message:

Field	Type	Description
`role`	string	`user`, `assistant`, or `system`.
`content`	string	The message content.

{
  "model": "gaur-nlq-v1",
  "messages": [
    { "role": "user", "content": "Show me weekly revenue trends." }
  ]
}

Response

200 OK with content type text/event-stream. The body is a server-sent events stream. Each data: line is a JSON chunk shaped like an OpenAI chat completion chunk:

{
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "created": 1769000000,
  "model": "gaur-nlq-v1",
  "choices": [
    { "index": 0, "delta": { "content": "Weekly " }, "finish_reason": null }
  ]
}

The stream ends with a chunk whose finish_reason is stop, then a final data: [DONE] line.

The delta object

choices[0].delta carries the streamed content. It has two relevant fields:

Field	Standard?	Description
`content`	Yes	A chunk of the agent's natural-language narrative.
`gaur_event`	No	A Gaur extension object carrying everything else: query results, chart suggestions, progress, and context.

gaur_event is not part of the OpenAI schema. A strict OpenAI SDK deserializes chunks into typed objects and drops unknown fields, so it will discard gaur_event and leave you with narrative text only. No result rows, no chart suggestions. Parse the SSE stream yourself, or use your SDK's extra-fields accessor, to read delta.gaur_event.

gaur_event types

Each gaur_event is an object with a type field:

`type`	Carries
`thinking`	The agent's progress and reasoning steps.
`assistant`	A chunk of narrative text. Also surfaced as `delta.content`.
`data`	The query result: rows and columns.
`chart_suggestion`	A suggested chart for the result data.
`context_state`	The objects and query the agent resolved for this turn.
`questionnaire`	Clarifying questions when the agent needs more input.
`error`	An error that occurred during the turn.

For an error event, the text is also mirrored into delta.content.

Status codes

Status	Meaning
`200`	Success. The stream begins.
`400`	Invalid request body.
`401`	Missing or invalid API key.
`403`	The API key does not authorize this consumer.
`502`	The natural-language request failed downstream.
`500`	Internal server error.

Example

curl -N -X POST https://<base-url>/v1/api/analytics-app/chat/completions \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gaur-nlq-v1",
    "messages": [{ "role": "user", "content": "Top regions by revenue this quarter" }]
  }'

See Chat for stream-handling code that reads both delta.content and delta.gaur_event.

Chat endpoint