> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

API operations for secrets. Browse the routes below for parameters, request examples, and responses.

API version: Selected per operation

## List secrets

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.

### Endpoint

```http
GET /v2/stable/secret
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

### Responses

#### 200

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

Schema:

```json
{
  "$ref": "#/components/schemas/StableSecretListResponseV2"
}
```

Example:

```json
{
  "secrets": [
    {
      "id": "<string>",
      "name": "<string>",
      "visibility": "<SecretVisibility>",
      "hasValue": true,
      "createdAt": "2026-09-10T00:00:00.000Z",
      "updatedAt": "2026-09-10T00:00:00.000Z"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v2/stable/secret?projectID=<projectID>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/secret?projectID=<projectID>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v2/stable/secret?projectID=<projectID>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf secret list --project-id <projectID>
```


## Create 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.

### Endpoint

```http
POST /v2/stable/secret
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableSecretCreateRequestV2"
      }
    }
  }
}
```

### Responses

#### 201

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableSecretResponseV2"
}
```

Example:

```json
{
  "secret": {
    "id": "<string>",
    "name": "<string>",
    "visibility": "restricted",
    "hasValue": true,
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z"
  },
  "environmentAlias": "<string>",
  "versionVariant": "draft"
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v2/stable/secret?projectID=<projectID>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "defaultValue": "<string>",
  "visibility": "masked"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/secret?projectID=<projectID>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<string>",
    "defaultValue": "<string>",
    "visibility": "masked"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v2/stable/secret?projectID=<projectID>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "name": "<string>",
      "defaultValue": "<string>",
      "visibility": "masked"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf secret create --project-id <projectID> <<'JSON'
{
  "name": "<string>",
  "defaultValue": "<string>",
  "visibility": "masked"
}
JSON
```


## List secret overrides

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.

### Endpoint

```http
GET /v1/stable/secret/override
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

### Responses

#### 200

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableSecretOverrideListResponse"
}
```

Example:

```json
{
  "overrides": [
    {
      "environmentAlias": "<string>",
      "versionVariant": "<VersionVariant>",
      "secretIDs": [
        "<string>"
      ]
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/secret/override?projectID=<projectID>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/secret/override?projectID=<projectID>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/secret/override?projectID=<projectID>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf secret list-overrides --project-id <projectID>
```


## Delete secret

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.

### Endpoint

```http
DELETE /v1/stable/secret/{secretID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `secretID`

Required · string

The ID of the secret to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

### Responses

#### 200

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDeleteResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request DELETE \
  --url 'https://realtime-api.voiceflow.com/v1/stable/secret/<secretID>?projectID=<projectID>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/secret/<secretID>?projectID=<projectID>', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.delete(
    'https://realtime-api.voiceflow.com/v1/stable/secret/<secretID>?projectID=<projectID>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf secret delete --secret-id <secretID> --project-id <projectID>
```


## Set secret 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.

### Endpoint

```http
PUT /v1/stable/secret/{secretID}/value
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `secretID`

Required · string

The ID of the secret to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableSecretValueRequest"
      }
    }
  }
}
```

### Responses

#### 200

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.

Schema:

```json
{
  "$ref": "#/components/schemas/StableSecretValueResponse"
}
```

Example:

```json
{
  "message": "<string>",
  "environmentAlias": "<string>",
  "versionVariant": "draft"
}
```

### Request examples

#### cURL

```bash
curl --request PUT \
  --url 'https://realtime-api.voiceflow.com/v1/stable/secret/<secretID>/value?projectID=<projectID>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "value": "<string>",
  "environmentAlias": "<string>",
  "versionVariant": "draft"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/secret/<secretID>/value?projectID=<projectID>', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "value": "<string>",
    "environmentAlias": "<string>",
    "versionVariant": "draft"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.put(
    'https://realtime-api.voiceflow.com/v1/stable/secret/<secretID>/value?projectID=<projectID>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "value": "<string>",
      "environmentAlias": "<string>",
      "versionVariant": "draft"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf secret set-value --secret-id <secretID> --project-id <projectID> <<'JSON'
{
  "value": "<string>",
  "environmentAlias": "<string>",
  "versionVariant": "draft"
}
JSON
```


## Schema definitions

### SecretVisibility

```json
{
  "type": "string",
  "enum": [
    "restricted",
    "masked"
  ],
  "x-enumNames": [
    "RESTRICTED",
    "MASKED"
  ]
}
```

### StableDeleteResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the deletion."
    }
  },
  "required": [
    "message"
  ]
}
```

### StableSecretCreateRequestV2

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^\\w{1,64}$",
      "description": "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": {
      "description": "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.",
      "type": "string",
      "minLength": 1
    },
    "visibility": {
      "default": "masked",
      "description": "Whether the value can be revealed in the Voiceflow UI. `restricted` secrets can never be read back by anyone.",
      "allOf": [
        {
          "$ref": "#/components/schemas/SecretVisibility"
        }
      ]
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
```

### StableSecretListResponseV2

```json
{
  "type": "object",
  "properties": {
    "secrets": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableSecretV2"
      }
    }
  },
  "required": [
    "secrets"
  ]
}
```

### StableSecretOverride

```json
{
  "type": "object",
  "properties": {
    "environmentAlias": {
      "type": "string",
      "description": "The alias of the environment carrying the override (e.g. `main`)."
    },
    "versionVariant": {
      "description": "Which version of the environment carries the override — its editable `draft` or its `published` copy.",
      "allOf": [
        {
          "$ref": "#/components/schemas/VersionVariant"
        }
      ],
      "enum": [
        "draft",
        "published"
      ],
      "x-enumNames": [
        "DRAFT",
        "PUBLISHED"
      ]
    },
    "secretIDs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The IDs of the secrets overridden on this environment version."
    }
  },
  "required": [
    "environmentAlias",
    "versionVariant",
    "secretIDs"
  ]
}
```

### StableSecretOverrideListResponse

```json
{
  "type": "object",
  "properties": {
    "overrides": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableSecretOverride"
      }
    }
  },
  "required": [
    "overrides"
  ]
}
```

### StableSecretResponseV2

```json
{
  "type": "object",
  "properties": {
    "secret": {
      "$ref": "#/components/schemas/StableSecretV2"
    },
    "environmentAlias": {
      "description": "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.",
      "type": "string"
    },
    "versionVariant": {
      "description": "Present along with `environmentAlias`: the version of that environment that now serves the value, always `published`, the version serving live traffic.",
      "allOf": [
        {
          "$ref": "#/components/schemas/VersionVariant"
        }
      ]
    }
  },
  "required": [
    "secret"
  ]
}
```

### StableSecretV2

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the secret, used to identify and delete it. A tool input binds the secret by NAME instead — a `{secret_name}` token inside `defaultValue` — not by this ID."
    },
    "name": {
      "type": "string",
      "description": "The name of the secret, unique within the project."
    },
    "visibility": {
      "description": "`masked` secrets can be revealed in the Voiceflow UI by users with permission; `restricted` secrets can never be read back by anyone.",
      "allOf": [
        {
          "$ref": "#/components/schemas/SecretVisibility"
        }
      ],
      "enum": [
        "restricted",
        "masked"
      ],
      "x-enumNames": [
        "RESTRICTED",
        "MASKED"
      ]
    },
    "hasValue": {
      "type": "boolean",
      "description": "Whether a project-level default value is currently stored for this secret."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    }
  },
  "required": [
    "id",
    "name",
    "visibility",
    "hasValue",
    "createdAt",
    "updatedAt"
  ]
}
```

### StableSecretValueRequest

```json
{
  "type": "object",
  "properties": {
    "value": {
      "type": "string",
      "minLength": 1,
      "description": "The secret value to store. Write-only — it can never be read back through this API."
    },
    "environmentAlias": {
      "description": "The alias of the environment to write (e.g. `staging`). Without it the value goes to the `main` environment. Requires `versionVariant`.",
      "type": "string",
      "minLength": 1
    },
    "versionVariant": {
      "description": "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.",
      "allOf": [
        {
          "$ref": "#/components/schemas/VersionVariant"
        }
      ]
    }
  },
  "required": [
    "value"
  ],
  "additionalProperties": false
}
```

### StableSecretValueResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the update."
    },
    "environmentAlias": {
      "description": "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.",
      "type": "string"
    },
    "versionVariant": {
      "description": "Which version of that environment now serves the value: `published`, the version serving live traffic, or `draft`, the one used when testing.",
      "allOf": [
        {
          "$ref": "#/components/schemas/VersionVariant"
        }
      ]
    }
  },
  "required": [
    "message"
  ]
}
```

### VersionVariant

```json
{
  "type": "string",
  "enum": [
    "draft",
    "published"
  ],
  "x-enumNames": [
    "DRAFT",
    "PUBLISHED"
  ]
}
```
