> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Variable
> Creates a new variable, this route must use the new V3 [endpoints](/api-reference/v3/intro).
## Example Request
```json theme={null}
{
"variable": {
"key": "user_name",
"type": "string",
"description": "Stores the user's name during conversation",
"defaultValue": "",
"isGlobal": true
}
}
```
The `key` must be unique within the agent. Duplicate keys will return a 400 error.
Set `isGlobal: true` for variables that should persist across conversation nodes.
## OpenAPI
````yaml POST /agents/{agentId}/variables
openapi: 3.0.3
info:
title: Convocore OpenAPI
description: Full API reference for Convocore
version: 1.0.4
servers:
- url: https://eu-gcp-api.vg-stuff.com/v3
security: []
paths:
/agents/{agentId}/variables:
post:
tags:
- Variables
summary: Add Variable
operationId: variableRouter-addVariableToAgent
parameters:
- name: agentId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
variable:
$ref: '#/components/schemas/object_7d59932c'
required:
- variable
additionalProperties: {}
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ApiSuccessWithData_21c02d'
default:
$ref: '#/components/responses/error'
security:
- Authorization: []
components:
schemas:
object_7d59932c:
type: object
properties:
in:
type: string
description: >-
Defines the location or context in which the field is utilized.
Common values include 'query', 'body', or 'header'.
type:
$ref: '#/components/schemas/string_ed9b3388'
value:
description: >-
The current assigned value of the field. This value is optional and
supports any type depending on the field's context.
defaultValue:
description: >-
A predefined value assigned to the field when no specific value is
provided. Useful for ensuring consistent behavior.
key:
type: string
description: >-
The unique key that identifies this tool field or variable. Often
used for referencing the field programmatically.
description:
type: string
description: >-
A detailed explanation of the field's purpose and usage. Helps users
understand the field's role in the system.
required:
type: boolean
description: >-
Indicates whether the presence of this field is mandatory for
successful operation. Defaults to false if unspecified.
reusable:
type: boolean
description: >-
Denotes whether this field can be reused across multiple contexts or
tools. Useful for reducing redundancy.
isEnv:
type: boolean
description: >-
Specifies if this field represents an environment variable,
typically used for configuration or deployment.
isSystem:
type: boolean
description: >-
Indicates whether this field is a system-level variable, reserved
for core operations or internal use.
isGlobal:
type: boolean
description: >-
If enabled, this field remains globally accessible to the agent
across all operational contexts. Useful for global constants.
additionalProperties: false
ApiSuccessWithData_21c02d:
type: object
properties:
success:
type: boolean
message:
type: string
data:
$ref: '#/components/schemas/object_6cf70218'
required:
- success
- message
- data
additionalProperties: false
string_ed9b3388:
type: string
enum:
- string
- number
- boolean
- system
description: >-
Specifies the variable type of the field. Acceptable values include
'string', 'number', 'boolean', and 'system'.
object_6cf70218:
type: object
properties:
id:
type: string
description: >-
A unique identifier for the field, ensuring it is distinct across
the system.
in:
type: string
description: >-
Defines the location or context in which the field is utilized.
Common values include 'query', 'body', or 'header'.
type:
$ref: '#/components/schemas/string_ed9b3388'
value:
description: >-
The current assigned value of the field. This value is optional and
supports any type depending on the field's context.
defaultValue:
description: >-
A predefined value assigned to the field when no specific value is
provided. Useful for ensuring consistent behavior.
key:
type: string
description: >-
The unique key that identifies this tool field or variable. Often
used for referencing the field programmatically.
description:
type: string
description: >-
A detailed explanation of the field's purpose and usage. Helps users
understand the field's role in the system.
required:
type: boolean
description: >-
Indicates whether the presence of this field is mandatory for
successful operation. Defaults to false if unspecified.
reusable:
type: boolean
description: >-
Denotes whether this field can be reused across multiple contexts or
tools. Useful for reducing redundancy.
isEnv:
type: boolean
description: >-
Specifies if this field represents an environment variable,
typically used for configuration or deployment.
isSystem:
type: boolean
description: >-
Indicates whether this field is a system-level variable, reserved
for core operations or internal use.
isGlobal:
type: boolean
description: >-
If enabled, this field remains globally accessible to the agent
across all operational contexts. Useful for global constants.
agentId:
type: string
description: >-
References the unique identifier of the agent associated with this
field. Helps in mapping fields to specific agents.
userId:
type: string
description: >-
References the unique identifier of the user associated with this
field. Useful for user-specific customizations.
required:
- id
additionalProperties: false
message_11569e:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
responses:
error:
description: Error response
content:
application/json:
schema:
type: object
properties:
message:
type: string
code:
type: string
issues:
type: array
items:
$ref: '#/components/schemas/message_11569e'
required:
- message
- code
additionalProperties: false
securitySchemes:
Authorization:
type: http
scheme: bearer
````