Update Dynamic Variables

Beta

PUT

https://api.speechify.ai/v1/agents/:agent_id/variables

PUT

/v1/agents/:agent_id/variables

$ curl -X PUT https://api.speechify.ai/v1/agents/agent_01jqr8x9zg5k2m3n4p5q6r7s8t/variables \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "variables": [
>     {
>       "key": "product_name",
>       "type": "string",
>       "default": null,
>       "description": "Product the agent is supporting."
>     },
>     {
>       "key": "support_tier",
>       "type": "number",
>       "default": null
>     },
>     {
>       "key": "account_metadata",
>       "type": "json",
>       "description": "Arbitrary account context injected into tool bodies."
>     }
>   ]
> }'

1 {
2   "variables": [
3     {
4       "key": "product_name",
5       "type": "string",
6       "default": null,
7       "description": "Name of the product the agent is supporting."
8     }
9   ],
10   "system_variables": [
11     {
12       "key": "product_name",
13       "description": "Example description."
14     }
15   ]
16 }

Replace the agent’s customer-scope dynamic variable definitions. The supplied list overwrites the stored list wholesale (same semantics as updateEvaluationConfig). Pass an empty array to clear all variables. Up to 20 variables per agent. Keys must match [a-zA-Z0-9_]+ and must not start with the reserved system__ prefix.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

agent_idstringRequired

Agent id (prefixed external id, agent_...).

Request

This endpoint expects an object.

variableslist of objectsRequired

The new variable list. Replaces the existing list entirely.

Response headers

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-Request-ID request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

Response

The updated variable catalogue.

variableslist of objects

Customer-defined variables for this agent.

system_variableslist of objects

Platform-populated system__* variables, provided for reference. This list is the same for every agent.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error