Re-bind a chart made from a template
const url = 'https://example.com/v1/yac/vis_instantiate';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"tool":"example","toolArgs":{"additionalProperty":{}},"dataSchema":"example"}'};
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/vis_instantiate \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "tool": "example", "toolArgs": { "additionalProperty": {} }, "dataSchema": "example" }'Re-instantiate a template-generated visualization with new bindings.
This is what lets a client change which field a generated chart splits by
without rewriting the finished spec. Rewriting is the tempting approach and
it does not hold: a template’s bindings can appear in transformations the
renamer has to know about one by one (a groupby entry, a derive expression,
a heading), so every new grammar feature silently falls outside it. Resolving
the template again is exact by construction, and placeholder resolution lives
in exactly one place (udiagent.vis_generate).
No LLM call, so — unlike /v1/yac/completions — no OpenAI key is required and nothing is metered.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Re-render a template-generated visualization with a binding changed.
Stateless, like YACQueryRequest: the caller sends back the provenance it
received in the render’s meta (tool_used / tool_args) together
with the same dataSchema, and gets a freshly instantiated spec. Nothing
is stored server-side, so any client that kept the provenance can re-bind —
including one restoring a saved conversation.
object
The template tool, from the render’s meta.tool_used.
The bindings, from the render’s meta.tool_args, with the changed one replaced. Values are column names and literal values, except a stratifier grouping, which is an object. A list is a <V*:list> literal: several values, any of which matches (a survival curve’s end events).
object
object
The same data package descriptor as the render’s request.
Example generated
{ "tool": "example", "toolArgs": { "additionalProperty": {} }, "dataSchema": "example"}Responses
Section titled “Responses”Successful Response
object
The instantiated UDI grammar spec.
object
The accepted bindings, pruned to parameters this template actually has, so a client can send them straight back for the next tweak. A stratifier grouping rides here as an object, like it does on the way in, and a list-valued literal as a list.
object
object
The re-bindable parameters, for a UI.
One re-bindable template parameter, as offered to a UI.
Two kinds. A field parameter swaps which column a channel is bound to,
and its value is that column’s name. A grouping parameter re-cuts a
stratifier into named strata, and its value is the grouping object (or
"" for the ungrouped default) — a client renders it from field and
fieldType, which say what is being cut and therefore which control fits.
A choice picks one of a fixed set of computations, listed in choices.
object
field, grouping or choice.
object
Example
{ "params": [ { "kind": "field", "encodings": [] } ]}bad_schema: dataSchema has no entities.
An error body. Authentication failures carry FastAPI’s detail
instead of error.
object
object
Example generated
{ "error": "example", "code": "example", "errors": [ "example" ], "detail": [ {} ]}Missing, invalid or expired token (detail).
An error body. Authentication failures carry FastAPI’s detail
instead of error.
object
object
Example generated
{ "error": "example", "code": "example", "errors": [ "example" ], "detail": [ {} ]}unknown_template: the template no longer exists.
An error body. Authentication failures carry FastAPI’s detail
instead of error.
object
object
Example generated
{ "error": "example", "code": "example", "errors": [ "example" ], "detail": [ {} ]}missing_bindings or invalid_bindings: the bindings do not fit the template or the schema; errors lists them.
An error body. Authentication failures carry FastAPI’s detail
instead of error.
object
object
Example generated
{ "error": "example", "code": "example", "errors": [ "example" ], "detail": [ {} ]}instantiate_failed: a template bug.
An error body. Authentication failures carry FastAPI’s detail
instead of error.
object
object
Example generated
{ "error": "example", "code": "example", "errors": [ "example" ], "detail": [ {} ]}templates_unavailable: this agent has no generated templates. 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": [ {} ]}