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

Returns every secret on the project in one response, with its name, visibility and whether a value is stored, never the value. A tool field binds a secret by name in a {secret_name} token.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

Response

200 - application/json

Returns every secret on the project with its ID, name, visibility, whether a value has been stored, and its timestamps; values are never included.

secrets
object[]
required
StableSecretV2 — see its attributes above
Current - 2026/09
Endpoint
POST
/v2/stable/secret

Creates a project secret, optionally with a value written to the main environment's published version and never read back. Names take letters, digits and underscores, because a {secret_name} token binds by name. Omit the value to leave a placeholder; MCP clients must.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

Request body

name
string
required

The name of the secret. Letters, digits and underscores only, at most 64 characters — this is what a {token} in a default-value field binds to. Must be unique within the project.

defaultValue
string

The secret's value, written to the main environment's published version, the one serving live traffic. It cannot be empty. Omit it to create the secret as a placeholder with no value — a teammate can fill it in later through the Voiceflow UI or CLI.

Minimum length: 1
visibility
object
default:"masked"

Whether the value can be revealed in the Voiceflow UI. restricted secrets can never be read back by anyone.

Response

201 - application/json

Returns the new secret with its generated ID, name, visibility and whether a value is stored. When a value was sent, the response also names the environment version it was written to.

secret
object
required
StableSecretV2 — see its attributes above
environmentAlias
string

Present when a defaultValue was sent: the alias of the environment that now serves the value (main). Omitted when no value was sent, or when the project has no main environment to name, such as a project that predates environments.

versionVariant
object

Present along with environmentAlias: the version of that environment that now serves the value, always published, the version serving live traffic.

Endpoint
GET
/v1/stable/secret/override

Returns which environment versions hold a value of their own for each secret, as secret IDs grouped by environment alias and draft or published variant; values are never included. The call is unpaginated: it takes no paging parameters, so one request yields the whole set.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

Response

200 - application/json

Returns one entry per environment version that holds a value for at least one secret, each with the environment alias, the draft or published variant, and the IDs of the secrets with a value there.

overrides
object[]
required
StableSecretOverride — see its attributes above
Endpoint
DELETE
/v1/stable/secret/{secretID}

Deletes a secret by ID, taking every value stored for it, on every version of every environment, with it. The response carries only a confirmation message, so refetch the secret list to see what is left.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

secretID
string
required

The ID of the secret to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

Response

200 - application/json

Confirms the secret was deleted. The body is a message only, so refetch the secret list and the override list to see it gone from both.

message
string
required

A human-readable message confirming the deletion.

Current - 2026/08
Endpoint
PUT
/v1/stable/secret/{secretID}/value

Sets a secret's value on one environment version. Without environmentAlias it writes main's published version, or its draft when versionVariant is draft; with it, versionVariant names the version. The value is never read back; MCP clients cannot call this.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

secretID
string
required

The ID of the secret to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

Request body

value
string
required

The secret value to store. Write-only — it can never be read back through this API.

Minimum length: 1
environmentAlias
string

The alias of the environment to write (e.g. staging). Without it the value goes to the main environment. Requires versionVariant.

Minimum length: 1
versionVariant
object

Which version of the environment to write: published, the version serving live traffic, or draft, the one used when testing. Required with environmentAlias. Without environmentAlias it defaults to published, and draft writes the main environment's draft version; a project with no main environment has no draft version, so the request is then handled as if versionVariant were omitted.

Response

200 - application/json

Confirms the value was stored and names the environment version it was written to. Only when there is no environment to name, such as a project that predates environments, does the confirmation stand alone.

message
string
required

A human-readable message confirming the update.

environmentAlias
string

The alias of the environment that now serves the value (e.g. main). Omitted only when there is no environment to name: the project predates environments, or no environmentAlias was given and the project has no main environment.

versionVariant
object

Which version of that environment now serves the value: published, the version serving live traffic, or draft, the one used when testing.

Schemas

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