Skip to navigation

Update agent variable

Creates or changes a variable with a fixed value (source is static) of an agent and returns it. The agent can use it as {{name}} in its texts. The value has 1 to 500 characters and the description up to 200; when you leave the description out, the current one is kept. An agent has at most 30 variables, and names starting with system__ are reserved. Variables that change at every call (source contact or call) are read-only here. Required scope: agents:operate. With a test key (vx_test_) it is simulated: nothing real happens and nothing is billed. Accepts an optional Idempotency-Key header. Retriable: when the operation itself fails with a 429, a 5xx or a temporary 409, the key is released and a retry with the same key runs the operation again; with no response at all, a retry with the same key returns the first outcome or runs the operation again. A 429 rate_limited from the request limit and 409 request_in_progress come before the operation and leave the key as it is: retry with the same key.

Authentication

AuthorizationBearer
API key created by an Owner or Admin of the organization. Never in the query string.

Path parameters

agent_idstringRequiredformat: "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"

Id of an agent of the organization, as returned by GET /agents.

namestringRequiredformat: "^[a-z][a-z0-9_]{0,63}$"

Lowercase letters, digits and underscore, starting with a letter, up to 64 characters. Names used by the platform (system__*) are reserved.

Headers

VoxAI-VersionenumOptional

API version for this request; defaults to the version the key is pinned to.

Allowed values:
Idempotency-KeystringOptionalformat: "^[A-Za-z0-9_-]{16,64}$"

A unique value you generate for each new operation (16 to 64 letters, digits, hyphen or underscore; a UUID works). Repeating the same request with the same key within 24 hours returns the first response and does nothing again, when that response was a success or a 4xx error the same request would always get again (not 429, and not the temporary 409 codes request_in_progress, caller_has_active_call and caller_request_in_progress: for those, and for a 5xx, see the note on retrying in the operation); the same key with a different request is refused with idempotency_key_reused.

Request

This endpoint expects an object.
valuestringRequired1-500 characters

The fixed value (1 to 500 characters).

descriptionstringOptional<=200 characters

What the variable is for (at most 200 characters). When omitted, the current description is kept.

Response

The variable already existed and was changed: created is false.

object"agent_variable"

Always agent_variable.

namestring
Name of the variable, as given in the path.
source"static"

Always static: only variables with a fixed value can be written here.

descriptionstring

The description now stored: the one you sent, or the one the variable already had. Empty when there is none.

valuestring
The fixed value now stored.
default_valueany

Always null: a variable with a fixed value has no fallback.

createdboolean

Whether the variable was created (201) or changed (200).

simulatedboolean

true when the request was made with a test key: every check ran but nothing was changed. false with a live key.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error