List the agent's variables
Return the full current agent snapshot as JSON, the agent row (name, voice, model, settings), the current version's system prompt + greeting, the tool list (each tool's name, kind, description, and for HTTP tools its url/method/headers/params/mock), the `workflow` (pre-call and post-call functions), variables (name + kind; secret values are never returned, plain values are), and the `privacy` block (recording + AI consent-disclosure enabled flags + copy, PII scrub level/categories, retention, telemetry, call-recording, null on an enabled flag means it inherits the workspace default). In the in-app builder this snapshot is already inlined every turn so calling it is just a post-edit re-read; over MCP it is the ONLY way to read the prompt/tools/variables/privacy, so call it whenever you need to see current state or confirm an edit landed. Pass `version: 'published'` (or a version number) to read the live version while a draft is open. For a cheap re-read after an edit, pass `toolName` (one tool's entry) or `sections` (only the groups you need, prompt/tools/variables/voice/behaviour/privacy/settings/model/workflow) instead of pulling the whole ~50KB snapshot. In the `model` group, `judgeModel` names the grading model (null = the platform default).
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Path Parameters
Workspace slug (GET /me lists yours).
Agent slug within the workspace.
Query Parameters
Return only this one tool's full entry (resolved by snake_case name) instead of the whole tool list, the cheap re-read after editing a single tool. If sections is also given, this scopes the tools section.
1 <= lengthRead a version other than the latest: "published" for the version live calls use, or a version number. Omit for the latest version (the draft when there is one). Use it to read or copy the published prompt while a draft is open.
Items per page, 1 to 200. Default 50.
1 <= value <= 200The next_cursor of the previous page.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X GET "https://example.com/workspaces/string/agents/string/variables"{
"data": [
{
"name": "string",
"kind": "string",
"hasValue": true,
"property1": null,
"property2": null
}
],
"has_more": true,
"next_cursor": "string"
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}Delete a variable DELETE
Delete a variable (plain or secret). For secrets, the underlying Vault row is dropped automatically via the cascade trigger. **Check that no tool URL/body/header references `{{name}}` first**, orphaned references will fail at publish time. To rename, call `rename_variable` instead.
Set a secret variable PUT
Create or update a SECRET per-agent variable (API key, OAuth token, anything sensitive) by passing the value directly. The value is written to the encrypted secret store and is NEVER returned. Use this, not set_plain_variable, for any credential. Typical flow: add_http_tool with a header like `Authorization: Bearer {{booking_api_key}}`, then set_secret_variable({ name: 'booking_api_key', value: '<the key>' }). Pass create: true to add a new secret without any risk of overwriting one that exists. The value passes through this conversation, so only send one the human handed you on purpose. To rename, use rename_variable, never delete-and-recreate (it orphans references). Works on a draft, or on a published latest version when you pass draftFrom. With draftFrom, a secret the live version already holds is refused, because the new draft shares its stored value and changing it would change the live call; call create_draft first to change it on purpose.