Set a plain variable
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.
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.
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/variables/string" \ -H "Content-Type: application/json" \ -d '{ "value": "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
}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.
Add a text source POST
Add a plain-text knowledge-base source to the agent. The content is chunked (~512 tokens), embedded at 1024 dimensions, and stored for retrieval via the `search_knowledge_base` tool at call time. Use when the caller's content lives in your prompt / docs / FAQ, paste it here rather than stuffing it into the system prompt. **The first source on an agent auto-attaches the `search_knowledge_base` tool**; the agent will start citing the new content on its next call.