Skip to main content
List Agent Variable Suggestions
A {{token}} is only valid in some places. This returns the ones that actually resolve for a given phase, so you can offer a picker instead of letting someone discover a typo at call time.

One notation

Everything is {{...}}, with one exception: angle brackets mark a tool the agent may call during the conversation, which is an instruction rather than a value. category tells you which group a row belongs to, for headings in a picker: custom, pre, api, call, agent, and activate for the <tool_name> rows.

Which phase to ask for

phase is required — the answer is different for each, and defaulting would hand someone a token that silently resolves to nothing.
Tools are built in the dashboard. The two tool phases describe what a tool’s request may reference; they do not let you create one. If your agent has no tools, pre_call and on_call return your variables plus the call. and agent. sets.
version_id takes a version number or a uuid, like every other version-taking route, and defaults to the newest version. Pass it to ask about a specific draft, since a tool added to one draft does not exist in another.
agent. and call. are pre-call only. By the time an on-call tool runs, the call’s own facts are already in the conversation — so they are offered where they are needed to open the call, and not where they would be noise.

Writing a variable in a prompt

Both {{order_id}} and {{custom.order_id}} resolve at call time. Prefer the bare form, which is what this endpoint returns and what the agent schema documents: saving a prompt that contains a bare {{order_id}} also registers the variable if it does not exist yet, so you can set its default afterwards. The dotted form is not picked up that way — it reads as a namespace reference, so nothing is created and, if you never declared order_id yourself, the token resolves to nothing. Inside a tool’s request body, either form works the same way.

Authorizations

Authorization
string
header
required

Your API key as a Bearer token, e.g. Authorization: Bearer vk_….

Path Parameters

agent_id
string
required

The agent's id, as GET /v1/agents returns it.

Query Parameters

phase
string
required

Which position the token will be used in. prompt — the system prompt or a greeting, which is the list a prompt editor wants. pre_call — inside the request body of a tool that runs before the call connects. on_call — inside the request body of a tool the agent calls mid-conversation. Tools themselves are built in the dashboard; these two lists say what their requests may reference.

version_id
string | null

Agent version; defaults to the newest one.

Response

Every token that resolves in the place you asked about.

value
string

The token to paste, exactly as it must appear.

category
string

What kind of token it is, for grouping a picker: custom, call, agent, pre, api, or activate for an <tool_name> row.