Variables
Variables

Set a secret variable

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.

PUT
/workspaces/{workspace}/agents/{agent}/secrets/{variable}

Authorization

bearerAuth
AuthorizationBearer <token>

A personal access token from Settings > API tokens.

In: header

Path Parameters

workspace*string

Workspace slug (GET /me lists yours).

agent*string

Agent slug within the workspace.

variable*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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 PUT "https://example.com/workspaces/string/agents/string/secrets/string" \  -H "Content-Type: application/json" \  -d '{    "value": "string"  }'
{
  "name": "string",
  "property1": null,
  "property2": null
}
{
  "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
}

List the agent's variables GET

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).

Set a plain variable PUT

Create or update a plain (non-secret) per-agent variable. These get interpolated into HTTP tool URLs and bodies, e.g. setting `tenant_id = acme-prod` lets a tool URL be `https://api/example.com/{{tenant_id}}/users`, and into the system prompt, where `{{opening_hours}}` reaches the model as its value. Only plain variables fill into the system prompt. Plain variables are stored in the row as-is and ARE inlined in the agent snapshot. **For API keys, OAuth tokens, anything sensitive, use the secret path instead**: `request_secret_variable` in the app (the operator types the value into a dialog you never see), or `set_secret_variable` over the MCP. Either way the value goes to the encrypted secret store and is never echoed; this tool rejects secret-shaped values. To rename an existing variable, use `rename_variable`, never delete-and-recreate, which orphans every reference.