Current - 2026/09
Endpoint
GET
/v2/stable/variable

Returns every variable in the project. A variable is a named slot of project state an agent can read and write. The call takes no paging parameters, so one request yields the whole set.

Request
Response

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Response

200 - application/json

Returns every variable defined in the project environment, each with its name, description, default value, color, and whether the platform owns it as a system variable.

variables
object[]
required
StableVariableV2 — see its attributes above
Current - 2026/09
Endpoint
POST
/v2/stable/variable

Adds a variable to the project, a named slot of project state an agent can read and write. The name takes letters, digits and underscores only, up to 64 characters, and must not already be used by a variable or entity in the environment. The response carries the ID that later calls address it by.

Request
Response

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Request body

name
string
required

The name of the variable. Letters, digits and underscores only, at most 64 characters — this is what a {token} in a text field binds to. Must not already be used by a variable or an entity in this environment. When updating, omit this field unless you are renaming: a variable stored before this rule can hold a name outside the grammar, and echoing that name back would be rejected.

color
string
required

The display color of the variable in the Voiceflow editor, as a hex code from the editor's color picker. Use #515A63 (the editor's default) unless the user asks for a color; otherwise pick the closest of #5B9FD7, #CB627B, #56B365, #DC8879, #9A63BC. Do not invent other hex codes.

defaultValue
string

The initial value of the variable at the start of a conversation.

More parameters
description
string

A short description of what the variable stores.

Response

201 - application/json

Returns the newly created variable in full, including the ID assigned to it and its creation timestamps.

variable
object
required
StableVariableV2 — see its attributes above
Current - 2026/09
Endpoint
POST
/v2/stable/variable/batch

Adds several variables to the project in one request, each taking the fields the single-create call takes, including its name rules. The response carries the created variables in the same shape the list call returns.

Request
Response

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Request body

variables
object[]
required
StableVariableCreateRequestV2 — see its attributes above

Response

201 - application/json

Returns the variables the request created, as an array, each carrying the ID assigned to it.

variables
object[]
required
StableVariableV2 — see its attributes above
Endpoint
DELETE
/v1/stable/variable/{variableID}

Deletes a single variable by ID. A variable is a named slot of project state an agent can read and write. The response carries only a confirmation message, so refetch the variables to see what is left.

Request
Response

Path parameters

variableID
string
required

The ID of the variable to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Response

200 - application/json

Confirms the variable was deleted. Only a message comes back, so refresh any cached copy of the project's variables.

message
string
required

A human-readable message confirming the deletion.

Error 404

No variable with that ID exists in the project and environment. A delete that has already succeeded returns this on a second attempt, so the operation is not idempotent - treat a 404 here as "already gone" rather than as a failure worth retrying.

Current - 2026/09
Endpoint
GET
/v2/stable/variable/{variableID}

Returns a single variable by ID, with the fields that define it. A variable is a named slot of project state an agent can read and write.

Request
Response

Path parameters

variableID
string
required

The ID of the variable to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Response

200 - application/json

Returns a single variable by ID, carrying its current description, default value, color, and timestamps.

variable
object
required
StableVariableV2 — see its attributes above
Current - 2026/09
Endpoint
PATCH
/v2/stable/variable/{variableID}

Changes an existing variable in place. Send name only when renaming, because a new name must use letters, digits and underscores and be unused by any variable or entity in the environment. The response carries only a confirmation message, so refetch the variable to read its new values.

Request
Response

Path parameters

variableID
string
required

The ID of the variable to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

The alias of the environment to operate on (e.g. main).

Request body

name
string

The name of the variable. Letters, digits and underscores only, at most 64 characters — this is what a {token} in a text field binds to. Must not already be used by a variable or an entity in this environment. When updating, omit this field unless you are renaming: a variable stored before this rule can hold a name outside the grammar, and echoing that name back would be rejected.

description
string

A short description of what the variable stores.

defaultValue
string

The initial value of the variable at the start of a conversation.

More parameters
color
string

The display color of the variable in the Voiceflow editor, as a hex code from the editor's color picker. Use #515A63 (the editor's default) unless the user asks for a color; otherwise pick the closest of #5B9FD7, #CB627B, #56B365, #DC8879, #9A63BC. Do not invent other hex codes.

Response

200 - application/json

Confirms the variable was updated. The body is a message rather than the revised variable, so read the variable back to see its new default value or description.

message
string
required

A human-readable message confirming the update.

Schemas

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.