Run a conversation turn
const url = 'https://example.com/v1/yac/completions';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"messages":[{}],"dataSchema":"example","dataDomains":"example","model":"example","filters":[],"issueReporting":false}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/yac/completions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "messages": [ {} ], "dataSchema": "example", "dataDomains": "example", "model": "example", "filters": [], "issueReporting": false }'Run one conversation turn.
The agent routes the latest message to tools (a chart, a filter change, an
answer, a clarifying question or a refusal) and returns one tool call per
outcome. Token use comes back in the X-Usage-* headers.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
The conversation in OpenAI chat format, including the tool calls of earlier turns as the client applied them.
object
The data package descriptor (Frictionless datapackage.json), as a JSON string.
Each column’s values or range, as a JSON string. The client may shorten high-cardinality columns.
The active filters as the client holds them: chat, host and chart brush, with the user’s edits (see udiagent.filters).
object
The client can send issue reports, so the agent may offer one. Honored only when the server records them (LangFuse configured).
Responses
Section titled “Responses”The turn’s outcomes, in the order to apply them. A quota refusal is a Rebuff here too, not an error status.
One outcome of a turn. A turn returns them in the order to apply them.
object
RenderVisualization, FilterData, FreeTextExplain, ClarifyVariable, Rebuff or OfferIssueReport.
The payload; its shape depends on name.
object
Example generated
[ { "name": "example", "arguments": {}, "meta": {} }]Headers
Section titled “Headers”Prompt tokens across every LLM call in the turn.
Completion tokens, reasoning included.
Prompt plus completion tokens.
Prompt tokens served from the provider’s cache.
Prompt tokens written to the provider’s cache.
Reasoning tokens, a subset of completion tokens.
The model the turn ran on.
Missing, invalid or expired token (detail). Or no_openai_key: the server has none and the request sent no X-OpenAI-Key. Or openai_key_rejected: OpenAI rejected the key.
An error body. Authentication failures carry FastAPI’s detail
instead of error.
object
object
Example generated
{ "error": "example", "code": "example", "errors": [ "example" ], "detail": [ {} ]}openai_key_refused: the server routes inference through Amazon Bedrock and refuses per-request X-OpenAI-Key headers.
An error body. Authentication failures carry FastAPI’s detail
instead of error.
object
object
Example generated
{ "error": "example", "code": "example", "errors": [ "example" ], "detail": [ {} ]}Validation Error
object
object
object
Example generated
{ "detail": [ { "loc": [ "example" ], "msg": "example", "type": "example", "input": "example", "ctx": {} } ]}llm_call_failed: the LLM API call failed (a model the key cannot use, a rate limit, a timeout).
An error body. Authentication failures carry FastAPI’s detail
instead of error.
object
object
Example generated
{ "error": "example", "code": "example", "errors": [ "example" ], "detail": [ {} ]}llm_backend_misconfigured: the server’s LLM backend is misconfigured. Or: The identity provider’s keys could not be fetched (JWT_JWKS_URL).
An error body. Authentication failures carry FastAPI’s detail
instead of error.
object
object
Example generated
{ "error": "example", "code": "example", "errors": [ "example" ], "detail": [ {} ]}