PromptVariableSpec
Declares a variable used by a profile's system-prompt template. Values are supplied through the conversation's prompt_variables.
When creating a conversation with an explicitly selected profile, a
variableSpecs entry with
required: true and no nonempty defaultValue
causes MISSING_REQUIRED_PROMPT_VARIABLES if the variable is missing. Supply the
value at creation. This validation is not repeated for each send or queued turn.
Set intended values explicitly even when the spec declares a default. A nonempty
defaultValue suppresses the creation-time missing-required error but is not
automatically inserted into the rendered prompt.
Usage profiles
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
name | string | Optional | Variable name referenced by the profile’s system-prompt template. |
description | string | Optional | Console hint + caller documentation. |
required | boolean | Optional | Whether a value is required for a profile explicitly selected at conversation creation. The current validation does not run for every send or queued turn. |
defaultValue | string | Optional | A nonempty value suppresses the creation-time missing-required error. It is not automatically inserted into the rendered prompt; supply intended values explicitly. |
type | string (VAR_TYPE_STRING, VAR_TYPE_NUMBER, VAR_TYPE_BOOL, VAR_TYPE_LIST) or integer (int32) | Optional | "" preserves the missing→empty behavior |
Values of type
Type used to coerce a prompt variable before placing it in the template context.
| Value | No. | Form | Meaning |
|---|---|---|---|
VAR_TYPE_STRING | 1 | Canonical | Treat the variable as text in the template context. |
VAR_TYPE_NUMBER | 2 | Canonical | Coerce the variable to a numeric value for arithmetic or numeric comparisons. |
VAR_TYPE_BOOL | 3 | Canonical | Coerce the variable to a boolean for template conditions. |
VAR_TYPE_LIST | 4 | Canonical | Provide a list that templates can iterate or join. |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
name | string | Optional | Variable name referenced by the profile’s system-prompt template. |
description | string | Optional | Console hint + caller documentation. |
required | boolean | Optional | Whether a value is required for a profile explicitly selected at conversation creation. The current validation does not run for every send or queued turn. |
defaultValue | string | Optional | A nonempty value suppresses the creation-time missing-required error. It is not automatically inserted into the rendered prompt; supply intended values explicitly. |
type | string (VAR_TYPE_STRING, VAR_TYPE_NUMBER, VAR_TYPE_BOOL, VAR_TYPE_LIST) or integer (int32) | Optional | "" preserves the missing→empty behavior |
Values of type
Type used to coerce a prompt variable before placing it in the template context.
| Value | No. | Form | Meaning |
|---|---|---|---|
VAR_TYPE_STRING | 1 | Canonical | Treat the variable as text in the template context. |
VAR_TYPE_NUMBER | 2 | Canonical | Coerce the variable to a numeric value for arithmetic or numeric comparisons. |
VAR_TYPE_BOOL | 3 | Canonical | Coerce the variable to a boolean for template conditions. |
VAR_TYPE_LIST | 4 | Canonical | Provide a list that templates can iterate or join. |
Where used
| Reference | Relationship |
|---|---|
| Create an agent profile | POST /api/v1/agent-profiles/create |
| Update an agent profile | POST /api/v1/agent-profiles/update |
| Get an agent profile | POST /api/v1/agent-profiles/get |
| Import a prompt library | POST /api/v1/agent-profiles/import |
| List agent profiles | POST /api/v1/agent-profiles/list |
| AgentProfile | Nested in model |
| AgentProfile | Nested in model |
Download the public reference contract.
Document: DOC-API-MODEL-prompt-variable-spec.