> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convocore.ai/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
description: EU Node.js API server
- url: https://na-gcp-api.vg-stuff.com/v3
description: NA Node.js API server
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:
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:
type: string
enum:
- string
- number
- boolean
- system
description: >-
Specifies the variable type of the field. Acceptable
values include 'string', 'number', 'boolean', and
'system'.
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
required:
- variable
additionalProperties: {}
responses:
'200':
description: Successful response
content:
application/json:
schema:
anyOf:
- type: object
properties:
success:
type: boolean
message:
type: string
data:
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:
type: string
enum:
- string
- number
- boolean
- system
description: >-
Specifies the variable type of the field.
Acceptable values include 'string', 'number',
'boolean', and 'system'.
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
required:
- success
- message
- data
additionalProperties: false
- {}
default:
$ref: '#/components/responses/error'
security:
- Authorization: []
components:
responses:
error:
description: Error response
content:
application/json:
schema:
type: object
properties:
message:
type: string
code:
type: string
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
additionalProperties: false
required:
- message
- code
additionalProperties: false
securitySchemes:
Authorization:
type: http
scheme: bearer
````