DOC-API-MODEL-schema-1hkadmq6cl#overview
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 variable_specs entry with required set to true and no nonempty default_value causes MISSING_REQUIRED_PROMPT_VARIABLES if the variable is missing. Supply its value at creation; this validation is not repeated for each send or queued turn.
Set intended values explicitly even when the specification declares a default. A nonempty default_value suppresses the creation-time missing-required error but is not automatically inserted into the rendered prompt.
Meaning and usage
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#meaning
See the definition above.
Usage profiles
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#fields
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#request
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#request-field-namename | string | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#request-field-descriptiondescription | string | Optional | Console hint + caller documentation. |
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#request-field-requiredrequired | boolean | Optional | Whether a value is required for a profile explicitly selected at conversation creation. This validation does not run for every send or queued turn. |
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#request-field-defaultvaluedefaultValue | string | Optional | A nonempty default value suppresses the creation-time missing-required error. It is not automatically inserted into the rendered prompt; supply intended values explicitly. |
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#request-field-typetype | string (VAR_TYPE_STRING, VAR_TYPE_NUMBER, VAR_TYPE_BOOL, VAR_TYPE_LIST) or integer (int32) | Optional; explicit presence | Optional runtime type for this variable in the template engine. |
name
Variable name referenced by the profile’s system-prompt template.
e.g. "user_name" → substituted for {{.user_name}}
Values of type
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#request-values-type
Type used to coerce a prompt variable before placing it in the template context. It determines creation-time validation, the authoring control, and how comparisons and joining values behave.
| Value | No. | Form | Meaning |
|---|---|---|---|
VAR_TYPE_STRING | 0 | Canonical | Treat the variable as text in the template context. |
VAR_TYPE_NUMBER | 1 | Canonical | See meaning below. |
VAR_TYPE_BOOL | 2 | Canonical | See meaning below. |
VAR_TYPE_LIST | 3 | Canonical | See meaning below. |
VAR_TYPE_NUMBER
Coerce the variable to a numeric value for arithmetic or numeric comparisons.
float64 in the template context (gt/lt/ge…)
VAR_TYPE_BOOL
Coerce the variable to a boolean for template conditions.
truthiness in {{if …}}
VAR_TYPE_LIST
Provide a list that templates can iterate or join.
[]interface{} — joinable, rangeable
In responses
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#response
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#field-nameSection ID: DOC-API-MODEL-schema-1hkadmq6cl#response-field-namename | string | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#field-descriptionSection ID: DOC-API-MODEL-schema-1hkadmq6cl#response-field-descriptiondescription | string | Optional | Console hint + caller documentation. |
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#field-requiredSection ID: DOC-API-MODEL-schema-1hkadmq6cl#response-field-requiredrequired | boolean | Optional | Whether a value is required for a profile explicitly selected at conversation creation. This validation does not run for every send or queued turn. |
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#field-defaultvalueSection ID: DOC-API-MODEL-schema-1hkadmq6cl#response-field-defaultvaluedefaultValue | string | Optional | A nonempty default value suppresses the creation-time missing-required error. It is not automatically inserted into the rendered prompt; supply intended values explicitly. |
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#field-typeSection ID: DOC-API-MODEL-schema-1hkadmq6cl#response-field-typetype | string (VAR_TYPE_STRING, VAR_TYPE_NUMBER, VAR_TYPE_BOOL, VAR_TYPE_LIST) or integer (int32) | Optional; explicit presence | Optional runtime type for this variable in the template engine. |
name
Variable name referenced by the profile’s system-prompt template.
e.g. "user_name" → substituted for {{.user_name}}
Values of type
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#response-values-type
Type used to coerce a prompt variable before placing it in the template context. It determines creation-time validation, the authoring control, and how comparisons and joining values behave.
| Value | No. | Form | Meaning |
|---|---|---|---|
VAR_TYPE_STRING | 0 | Canonical | Treat the variable as text in the template context. |
VAR_TYPE_NUMBER | 1 | Canonical | See meaning below. |
VAR_TYPE_BOOL | 2 | Canonical | See meaning below. |
VAR_TYPE_LIST | 3 | Canonical | See meaning below. |
VAR_TYPE_NUMBER
Coerce the variable to a numeric value for arithmetic or numeric comparisons.
float64 in the template context (gt/lt/ge…)
VAR_TYPE_BOOL
Coerce the variable to a boolean for template conditions.
truthiness in {{if …}}
VAR_TYPE_LIST
Provide a list that templates can iterate or join.
[]interface{} — joinable, rangeable
Where used
Section ID: DOC-API-MODEL-schema-1hkadmq6cl#where-used
| Reference | Relationship |
|---|---|
| Create an agent profile | POST /api/v1/agent-profiles/create |
| 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 |
| Update an agent profile | POST /api/v1/agent-profiles/update |
Models containing this value
| Model | Relationship |
|---|---|
| AgentProfile | Nested in model |
| AgentProfile | Nested in model |
Download the public reference contract.
Document ID: DOC-API-MODEL-schema-1hkadmq6cl