# Get agent
Source: https://www.voiceflow.com/docs/api-reference/agent/get-agent
/specs-prettified/realtime/openapi.stable.json get /v1/stable/agent
Returns the environment’s agent: the global prompt, the instructions that route a turn, and the settings wrapping both.
# Update agent
Source: https://www.voiceflow.com/docs/api-reference/agent/update-agent
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/agent
Changes the agent that shapes every turn - its global prompt, its routing instructions, or its settings - in the environment named by the request.
# Query API tool usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-api-tool-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/api-tool-usage/project/{projectID}
Reports how often each API tool was called, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query call count
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-call-count
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/call-count/project/{projectID}
Reports how many voice calls were placed, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query call duration
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-call-duration
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/call-duration/project/{projectID}
Reports how much time was spent on voice calls, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query category token usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-category-token-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/category-token-usage/project/{projectID}
Reports how many tokens each category consumed, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query daily token usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-daily-token-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/daily-token-usage/organization/{organizationID}
Reports how many tokens were consumed, bucketed by day, for one organization over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query entity token usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-entity-token-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/entity-token-usage/organization/{organizationID}
Reports how many tokens each entity consumed, for one organization over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query function usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-function-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/function-usage/project/{projectID}
Reports how often each function ran, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query hourly organization token usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-hourly-organization-token-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/hourly-token-usage/organization/{organizationID}
Reports how many tokens were consumed, bucketed by hour, for one organization over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query hourly project token usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-hourly-project-token-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/hourly-token-usage/project/{projectID}
Reports how many tokens were consumed, bucketed by hour, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query integration usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-integration-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/integration-usage/project/{projectID}
Reports how often each integration ran, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query intent usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-intent-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/intent-usage/project/{projectID}
Reports how often each intent matched, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query knowledge base document usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-knowledge-base-document-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/knowledge-base-document-usage/project/{projectID}
Reports how often each knowledge base document was retrieved, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query MCP tool usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-mcp-tool-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/mcp-tool-usage/project/{projectID}
Reports how often each MCP tool was called, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query organization token usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-organization-token-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/token-usage/organization/{organizationID}
Reports how many tokens were consumed, for one organization over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query playbook usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-playbook-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/playbook-usage/project/{projectID}
Reports how often each playbook ran, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query project interaction count
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-project-interaction-count
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/interaction-count/project/{projectID}
Reports how many interactions were exchanged, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query project token usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-project-token-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/token-usage/project/{projectID}
Reports how many tokens were consumed, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query project transcript count
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-project-transcript-count
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/transcript-count/project/{projectID}
Reports how many conversations were recorded, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query prompt usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-prompt-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/prompt-usage/project/{projectID}
Reports how often each prompt was used, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query transcript cost
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-transcript-cost
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/transcript-cost/project/{projectID}
Reports what those conversations cost in model spend, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query unique user count
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-unique-user-count
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/unique-user-count/project/{projectID}
Reports how many distinct users held a conversation, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query workflow usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-workflow-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/workflow-usage/project/{projectID}
Reports how often each workflow ran, for one project over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query workspace interaction count
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-workspace-interaction-count
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/interaction-count/workspace/{workspaceID}
Reports how many interactions were exchanged, for one workspace over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query workspace token usage
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-workspace-token-usage
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/token-usage/workspace/{workspaceID}
Reports how many tokens were consumed, for one workspace over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# Query workspace transcript count
Source: https://www.voiceflow.com/docs/api-reference/analytics/query-workspace-transcript-count
/specs-prettified/realtime/openapi.stable.json post /v1/stable/analytics/query/transcript-count/workspace/{workspaceID}
Reports how many conversations were recorded, for one workspace over a date range. The request body takes `startDate`, `endDate` and an `interval`, the same shape the other analytics measures take.
# What the REST API covers
Source: https://www.voiceflow.com/docs/api-reference/api-overview
Everything the Voiceflow REST API can do, grouped by the job you came to do: build an agent, run a conversation, publish it, and measure it.
The Voiceflow REST API covers the whole lifecycle of an agent. You can build
one from parts, run conversations against it, publish it through environments,
and read back what happened, all without opening the Studio.
Every request carries a [personal access token](/docs/api-reference/authentication).
One credential authenticates the REST API, the `vf` CLI, and the MCP server.
```bash
curl "https://realtime-api.voiceflow.com/v1/stable/workspace" \
-H "Authorization: Bearer $VF_PAT"
```
New to the API? [Quickstart](/docs/api-reference/quickstart) gets you a first
response in a few minutes.
## Build and run
Create and manage the pieces an agent is built from: playbooks, functions, tools, API tools, MCP servers, variables and knowledge base documents.
Run conversations against an agent over HTTP. Send what a user would say, read the traces that come back, and inspect or reset the state between turns.
Ship changes with environments. Edit a draft, publish it live, clone one to work in isolation, merge it back, and split traffic between versions.
Create and administer the containers your agents live in: workspaces that group projects and people, and projects that each own a single agent.
## Measure and improve
Read the conversations your agent actually had. Search transcripts, fetch a single one, and attach your own properties to record what happened.
Score conversations against criteria you define, so agent quality becomes a number you can track over time instead of a sample you skim.
Replay scripted conversations against your agent and assert what it does, so a change that breaks a scenario fails loudly instead of silently.
Query usage and cost: tokens, calls, conversations and unique users, plus the spend attributed to individual functions, playbooks and tools.
## Webhooks
Receive events whenever conversations start or end, on both chat and voice.
Receive events when projects are created, published, or deleted.
# Create many variables
Source: https://www.voiceflow.com/docs/api-reference/api-tool-variable/create-many-variables
/specs-prettified/realtime/openapi.stable.json post /v1/stable/api-tool-variable/batch
Adds several API tool variables to its API tool in one request, each taking the fields the single-create call takes. The response carries the created API tool variables in the same shape the list call returns.
# Create variable
Source: https://www.voiceflow.com/docs/api-reference/api-tool-variable/create-variable
/specs-prettified/realtime/openapi.stable.json post /v1/stable/api-tool-variable
Adds a API tool variable to its API tool, an input an API tool substitutes into its request. The response carries the ID that later calls address it by.
# Delete variable
Source: https://www.voiceflow.com/docs/api-reference/api-tool-variable/delete-variable
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/api-tool-variable/{variableID}
Deletes a single API tool variable by ID. An API tool variable is an input an API tool substitutes into its request. The response carries only a confirmation message, so refetch the API tool variables to see what is left.
# Get variable
Source: https://www.voiceflow.com/docs/api-reference/api-tool-variable/get-variable
/specs-prettified/realtime/openapi.stable.json get /v1/stable/api-tool-variable/{variableID}
Returns a single API tool variable by ID, with the fields that define it. An API tool variable is an input an API tool substitutes into its request.
# List variables
Source: https://www.voiceflow.com/docs/api-reference/api-tool-variable/list-variables
/specs-prettified/realtime/openapi.stable.json get /v1/stable/api-tool-variable
Returns every API tool variable in its API tool. An API tool variable is an input an API tool substitutes into its request. The call takes no paging parameters, so one request yields the whole set.
# Update variable
Source: https://www.voiceflow.com/docs/api-reference/api-tool-variable/update-variable
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/api-tool-variable/{variableID}
Changes an existing API tool variable in place. The response carries only a confirmation message, so refetch the API tool variable to read its new values.
# Create API tool
Source: https://www.voiceflow.com/docs/api-reference/api-tool/create-api-tool
/specs-prettified/realtime/openapi.stable.json post /v1/stable/api-tool
Adds a API tool to the environment, a saved HTTP request an agent can make. The response carries the ID that later calls address it by.
# Create many API tools
Source: https://www.voiceflow.com/docs/api-reference/api-tool/create-many-api-tools
/specs-prettified/realtime/openapi.stable.json post /v1/stable/api-tool/batch
Adds several API tools to the environment in one request, each taking the fields the single-create call takes. The response carries the created API tools in the same shape the list call returns.
# Delete API tool
Source: https://www.voiceflow.com/docs/api-reference/api-tool/delete-api-tool
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/api-tool/{toolID}
Deletes a single API tool by ID. An API tool is a saved HTTP request an agent can make. The response carries only a confirmation message, so refetch the API tools to see what is left.
# Get API tool
Source: https://www.voiceflow.com/docs/api-reference/api-tool/get-api-tool
/specs-prettified/realtime/openapi.stable.json get /v1/stable/api-tool/{toolID}
Returns a single API tool by ID, with the fields that define it. An API tool is a saved HTTP request an agent can make.
# List API tools
Source: https://www.voiceflow.com/docs/api-reference/api-tool/list-api-tools
/specs-prettified/realtime/openapi.stable.json get /v1/stable/api-tool
Returns every API tool in the environment. An API tool is a saved HTTP request an agent can make. The call takes no paging parameters, so one request yields the whole set.
# Update API tool
Source: https://www.voiceflow.com/docs/api-reference/api-tool/update-api-tool
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/api-tool/{toolID}
Changes an existing API tool in place. The response carries only a confirmation message, so refetch the API tool to read its new values.
# Personal access tokens
Source: https://www.voiceflow.com/docs/api-reference/authentication
Create a personal access token in Settings, send it as a Bearer token, and pass the project and environment your request should run against.
Every request to the Voiceflow API carries a **personal access token**. The
same token authenticates the REST API, the `vf` CLI, and optionally the MCP
server, so there is one credential to create and one to rotate.
## Create a token
Open **Settings** → **Access tokens** and choose **Create personal access
token**. Give it a name you will recognise later and pick how long it should
last.
The token is shown once, at creation. After you close the dialog only a
masked version is visible, so store it somewhere durable before you leave the
page.
A token looks like this, and always begins with `vfp_`:
```text
vfp_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6
```
### Expiry
Tokens expire. You choose the lifetime when you create one:
| Option | Lifetime |
| --- | --- |
| In a day | 1 day |
| In a week | 7 days |
| In a month | 30 days (default) |
| In 3 months | 90 days |
| In a year | 365 days |
There is no non-expiring option, so any long-running integration needs a
calendar reminder to issue a replacement before the current token lapses.
### What a token can reach
A personal access token acts as **you**. It carries the same access your own
account has, across every workspace you belong to, and cannot be narrowed to a
single workspace or project.
Two consequences worth planning around:
- Treat a token like a password. Anyone holding it can do anything you can do.
- Tokens can only be created through the dashboard, so a person has to issue and
rotate the one your automation uses.
## Send the token
Pass it in the `Authorization` header as a Bearer token:
```bash
curl "https://realtime-api.voiceflow.com/v1/stable/workspace" \
-H "Authorization: Bearer $VF_PAT"
```
## Target a project and environment
Most endpoints act on one project, and many act on one environment inside it.
Both are query parameters rather than path segments:
```bash
curl "https://realtime-api.voiceflow.com/v1/stable/function?projectID=$VF_PROJECT_ID&environmentAlias=main" \
-H "Authorization: Bearer $VF_PAT"
```
Find `projectID` in **Settings** → **General** under Metadata.
`environmentAlias` names an [environment](/docs/documentation/deploy/environments/overview)
in that project. New projects start with a single environment called `main`.
Passing an alias the project does not have returns:
```json
{ "statusCode": 400, "message": "invalid environment tag" }
```
List the aliases a project actually has with
[List environments](/docs/api-reference/environment/list-environments).
## Revoke a token
Delete it from **Settings** → **Access tokens**. Revocation takes effect
immediately, so anything using that token stops working the moment you remove
it. Issue and deploy the replacement first.
# Delete state
Source: https://www.voiceflow.com/docs/api-reference/conversation-state/delete-state
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/conversation-state/{userID}
Discards the stored state for one conversation, so the next turn on that `userID` begins from the start. The response carries only a confirmation message.
# Get state
Source: https://www.voiceflow.com/docs/api-reference/conversation-state/get-state
/specs-prettified/realtime/openapi.stable.json get /v1/stable/conversation-state/{userID}
Returns the stored state for one conversation - where it stands and what its variables hold - addressed by the same `userID` used to run it.
# Update state
Source: https://www.voiceflow.com/docs/api-reference/conversation-state/update-state
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/conversation-state/{userID}
Changes the stored state of a live conversation, which is how a caller seeds or corrects variables between turns without replaying the conversation.
# Update variables
Source: https://www.voiceflow.com/docs/api-reference/conversation-state/update-variables
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/conversation-state/{userID}/variables
Updates variables in the conversation state by merging with the properties in the request body.
# Send
Source: https://www.voiceflow.com/docs/api-reference/conversation/send
/specs-prettified/realtime/openapi.stable.json put /v1/stable/conversation/{userID}
Advances a conversation by one turn: the body carries the action to apply, and the response carries the traces the agent produced in reply.
# WebSocket
Source: https://www.voiceflow.com/docs/api-reference/conversations-api/interact-socket
Hold a persistent socket.io connection to the Voiceflow runtime for real-time conversations, and read the events it emits over that channel.
The Voiceflow WebSocket runtime uses [socket.io](https://socket.io/) to establish persistent, bidirectional connections for real-time conversational AI interactions.
This is a different transport from the [conversation
endpoints](/docs/api-reference/conversation/send), not a different version of
them. Those take one turn per request and return when the turn is done. A
socket stays open, pushes traces as they are produced, and yields a
`sessionKey` that server-side event endpoints need in order to target a
running session.
Find the [socket.io client](https://github.com/socketio) in your respective development language. This documentation will use javascript, but the fundamentals remain the same.
## Connection configuration
```js
import { io } from 'socket.io-client';
const socket = io('https://general-runtime.voiceflow.com', {
path: '/v4/interact/socket',
timeout: 10000,
transports: ['websocket', 'polling', 'webtransport'], // optional fallbacks
reconnection: true,
tryAllTransports: true,
reconnectionDelay: 1000,
reconnectionAttempts: 5,
reconnectionDelayMax: 5000,
});
```
[socket.io](http://socket.io) allows for fallback transports if the end-client does not allow the websocket protocol (wss://), common in many firewalls and enterprise settings.
## Lifecycle
A session is not the same as the socket.io connection. You can disconnect/reconnect multiple times and still continue the same conversation session.
For more information on socket.io lifecycle management, reference [documentation](https://socket.io/docs/v4/client-api/).
### Initialization sequence
1. Wait for `connect`. This is a socket.io level connection established.
2. Send `client.start`. Send voiceflow project metadata/config \+ optional `sessionKey`.
3. Wait for `client.started`. Client handshake, confirms configuration.
4. If `client.started` specifies `newSessionRequired`:
1. Send `session.create`.
2. Wait for `session.created`. Save returned `sessionKey` for future use.
5. Agent is now ready for interactions
```ts
// save sessionKey on client side for future reconnections
let sessionKey: string | undefined;
// socket.io level connection
socket.on('connect', () => {
// voiceflow client handshake
socket.emit('client.start', { sessionKey, ...metadata });
socket.once('client.started', (payload: { newSessionRequired: boolean }) => {
if (payload.newSessionRequired === false) {
return ready();
}
// session create handshake
socket.emit('session.create', {});
socket.once('session.created', (payload: { sessionKey: string }) => {
sessionKey = payload.sessionKey;
ready();
});
});
})
```
### Action Lifecycle
Once the session is ready, you can now send actions to the agent and get responses back.
1. send new action with `action.send`, i.e. `{ type: 'text', payload: 'hello' }`
2. get back a status `action.status` either `status: 'accepted' | 'rejected'`
3. if `status: accepted`:
1. get back agent responses with `action.trace`, display to user
2. get `action.status` with `status: 'completed'`
This represents the back and forth conversation with the agent.
Try to not send a new action while an existing action is running. While this is supported, it can make it harder to debug user state and lead to certain race conditions.
Instead wait for `status: 'completed'` or `status: 'rejected'` after sending an action.
### Conversation Lifecycle
#### Start
To start the conversation from the beginning, your first action should be:
```ts
socket.emit('action.send', {
action: { type: 'launch', payload: {} }
});
```
It is also possible to launch from specific points in the conversation with [events](https://docs.voiceflow.com/docs/introduction-to-events):
```ts
socket.emit('action.send', {
action: { type: 'event', payload: { event: { name: 'event_name' } } }
});
```
#### End
The session ending also signals that the conversation has ended. This can also occur because of timeouts.
```ts
socket.on('session.ended', () => {
// cleanup code
})
```
## Client events
### `client.start`
Initial Voiceflow metadata and configuration to validate and set up the client. This is aways the first message that the client should send to the server after socket.io successfully connects. Server will respond with `client.started`.
#### Payload
`?:` denotes optional properties.
```ts
interface ClientStartPayload {
userID: string; // primary user identifier
projectID: string; // voiceflow projectID
// alias of the environment to use. Omit to route the session via the project's
// traffic split (hashed by userID, so a given userID routes consistently).
environmentID?: string;
// session to reconnect to, ignore if new session
sessionKey?: string | null;
// voiceflow project API Key (under settings), do not set for public facing clients
authorization?: string;
config?: {
// break up LLM responses into live chunks [default: false]
completionEvents: boolean;
// timezone in IANA (tz database) for the vf_user_timezone variable
userTimezone?: string;
audioEvents: boolean; // enable TTS audio chunk responses
audioEncoding?: 'audio/x-mulaw' | 'audio/pcm'; // audio response format
};
}
```
#### Example Call
```ts
socket.emit('client.start', {
userID: 'test@test.com',
projectID: '6939bedf69c7ce5ee7a108ed',
authorization: 'VF.DM...',
config: {
completionEvents: true
};
});
```
### `session.create`
Creates a new session for the user. Should be sent after `client.started` indicates `newSessionRequired: true`. Server will respond with `session.created`.
#### Example Call
```ts
socket.emit('session.create', {});
```
### `action.send`
Sends a user action to the server. A valid session must already exist. Server will respond with `action.status` and `action.trace` events.
[See possible action types in the `action` body of interaction requests.](/docs/api-reference/conversation/send).
#### Payload
```ts
interface ActionSendPayload {
action: {
// request type: "text" | "intent" | "launch" | "event" | "action" | etc.
type: string;
// action-specific payload
payload?: string | object;
};
}
```
#### Example Call
```ts
socket.emit('action.send', {
action: {
type: 'text',
payload: 'Hello, how are you?'
}
});
```
## Server events
### `client.started`
Server ack to `client.start`, informs if a new session needs to be created
#### Payload
```ts
interface ClientStartedPayload {
newSessionRequired: boolean
}
```
#### Example
```ts
socket.on('client.started', (payload: ClientStartedPayload) => {
if (payload.newSessionRequired) {
socket.emit('session.create', {});
} else {
// session is now ready for interactions
}
});
```
### `session.created`
Confirms that a new session has been created. Client should store the `sessionKey` for future reconnections.
#### Payload
```ts
interface SessionCreatedPayload {
sessionKey: string; // JWT session key to store and use for reconnections
}
```
#### Example
```ts
socket.on('session.created', (payload: SessionCreatedPayload) => {
localStorage.setItem('sessionKey', payload.sessionKey);
// session is now ready for interactions
});
```
### `session.ended`
Indicates that the conversation session has ended. Client should close the session and optionally display a workflow to create a new one.
#### Payload
```ts
interface SessionEndedPayload {
// reason for session ending (e.g., "end_of_diagram", "inactivity_timeout", etc.)
reason: string;
}
```
### `action.trace`
Represents agent responses and debugging information for an action. [See possible trace types](/docs/api-reference/trace-types).
#### Payload
```ts
type ActionTracePayload = {
// trace object containing agent response data (speak, text, audio, etc.)
trace: Trace;
// message identifier matching the action.send messageID
messageID: string;
}
```
#### Example
```ts
socket.on('action.trace', (payload: ActionTracePayload) => {
// Handle trace data (speech, text, audio chunks, etc.)
console.log('Trace received:', payload.trace);
});
```
### `action.status`
Indicates the status of an action that was sent via `action.send`. This event is sent when an action is accepted, rejected, or completed.
#### Payload
```ts
interface ActionStatusPayload {
status: 'accepted' | 'rejected' | 'completed'; // action status
messageID: string; // message identifier matching the action.send messageID
reason?: string; // optional reason for rejection or completion
}
```
### `server.restart`
Server is gracefully shutting down and informing the client to reconnect to a different server instance.
#### Payload
```ts
interface ServerRestartPayload {
action?: {
type: string;
payload?: string | object;
diagramID?: string;
time?: number;
}; // optional action to replay after reconnection
}
```
### `error`
General error message from the server. May occur at any point during the connection.
#### Payload
```ts
interface ErrorPayload {
code?: string; // optional error code
error: string; // error message
}
```
# Create table document
Source: https://www.voiceflow.com/docs/api-reference/document/create-table-document
/specs-prettified/realtime/openapi.stable.json post /v1/stable/document/table
Adds a document to the knowledge base, a source the knowledge base retrieves from. The response carries the ID that later calls address it by.
# Create text document
Source: https://www.voiceflow.com/docs/api-reference/document/create-text-document
/specs-prettified/realtime/openapi.stable.json post /v1/stable/document/text
Adds a document to the knowledge base, a source the knowledge base retrieves from. The response carries the ID that later calls address it by.
# Create URL document
Source: https://www.voiceflow.com/docs/api-reference/document/create-url-document
/specs-prettified/realtime/openapi.stable.json post /v1/stable/document/url
Adds a document to the knowledge base, a source the knowledge base retrieves from. The response carries the ID that later calls address it by.
# Delete document
Source: https://www.voiceflow.com/docs/api-reference/document/delete-document
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/document/{documentID}
Deletes a single document by ID. A document is a source the knowledge base retrieves from. The response carries only a confirmation message, so refetch the documents to see what is left.
# Get document
Source: https://www.voiceflow.com/docs/api-reference/document/get-document
/specs-prettified/realtime/openapi.stable.json get /v1/stable/document/{documentID}
Returns a single document by ID, with the fields that define it. A document is a source the knowledge base retrieves from.
# List documents
Source: https://www.voiceflow.com/docs/api-reference/document/list-documents
/specs-prettified/realtime/openapi.stable.json get /v1/stable/document
Returns every document in the knowledge base. A document is a source the knowledge base retrieves from. The call takes no paging parameters, so one request yields the whole set.
# Update document
Source: https://www.voiceflow.com/docs/api-reference/document/update-document
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/document/{documentID}
Changes an existing document in place. The response carries only a confirmation message, so refetch the document to read its new values.
# Clone environment
Source: https://www.voiceflow.com/docs/api-reference/environment/clone-environment
/specs-prettified/realtime/openapi.stable.json post /v1/stable/environment/{environmentAlias}/clone
Copies an environment into a new one under an alias you choose, giving somewhere to change the agent without touching the environment being cloned.
# Compile environment
Source: https://www.voiceflow.com/docs/api-reference/environment/compile-environment
/specs-prettified/realtime/openapi.stable.json put /v1/stable/environment/{environmentAlias}/compile
Rebuilds the environment’s runtime form from its current definition, which is what a conversation actually executes against.
# Delete environment
Source: https://www.voiceflow.com/docs/api-reference/environment/delete-environment
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/environment/{environmentAlias}
Deletes a single environment by ID. An environment is one draft-and-published copy of the agent. The response carries only a confirmation message, so refetch the environments to see what is left.
# Export environment
Source: https://www.voiceflow.com/docs/api-reference/environment/export-environment
/specs-prettified/realtime/openapi.stable.json get /v1/stable/environment/{environmentAlias}/export
Serialises the whole environment - its agent, playbooks, tools and knowledge base - into a single document you can archive or move to another project.
# Get environment
Source: https://www.voiceflow.com/docs/api-reference/environment/get-environment
/specs-prettified/realtime/openapi.stable.json get /v1/stable/environment/{environmentAlias}
Returns a single environment by ID, with the fields that define it. An environment is one draft-and-published copy of the agent.
# List environments
Source: https://www.voiceflow.com/docs/api-reference/environment/list-environments
/specs-prettified/realtime/openapi.stable.json get /v1/stable/environment
Returns every environment in the project. An environment is one draft-and-published copy of the agent. The call takes no paging parameters, so one request yields the whole set.
# Merge environments
Source: https://www.voiceflow.com/docs/api-reference/environment/merge-environments
/specs-prettified/realtime/openapi.stable.json put /v1/stable/environment/merge
Folds the contents of one environment into another, so work done in a clone can be brought back to the environment it was cloned from.
# Publish environment
Source: https://www.voiceflow.com/docs/api-reference/environment/publish-environment
/specs-prettified/realtime/openapi.stable.json post /v1/stable/environment/{environmentAlias}/publish
Promotes the environment’s draft to its published version, which is the copy real traffic reaches. The request names the release so it can be told apart in the history.
# Update environment
Source: https://www.voiceflow.com/docs/api-reference/environment/update-environment
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/environment/{environmentAlias}
Changes an existing environment in place. The response carries only a confirmation message, so refetch the environment to read its new values.
# Update traffic split
Source: https://www.voiceflow.com/docs/api-reference/environment/update-traffic-split
/specs-prettified/realtime/openapi.stable.json put /v1/stable/environment/update-traffic-split
Changes an existing environment in place. The response carries only a confirmation message, so refetch the environment to read its new values.
# Create evaluation
Source: https://www.voiceflow.com/docs/api-reference/evaluation/create-evaluation
/specs-prettified/realtime/openapi.stable.json post /v1/stable/evaluation
Adds a evaluation to the project, a criterion a model scores past conversations against. The response carries the ID that later calls address it by.
# Delete evaluation
Source: https://www.voiceflow.com/docs/api-reference/evaluation/delete-evaluation
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/evaluation/{evaluationID}
Deletes a single evaluation by ID. An evaluation is a criterion a model scores past conversations against. The response carries only a confirmation message, so refetch the evaluations to see what is left.
# Get evaluation
Source: https://www.voiceflow.com/docs/api-reference/evaluation/get-evaluation
/specs-prettified/realtime/openapi.stable.json get /v1/stable/evaluation/{evaluationID}
Returns a single evaluation by ID, with the fields that define it. An evaluation is a criterion a model scores past conversations against.
# List evaluations
Source: https://www.voiceflow.com/docs/api-reference/evaluation/list-evaluations
/specs-prettified/realtime/openapi.stable.json get /v1/stable/evaluation
Returns every evaluation in the project. An evaluation is a criterion a model scores past conversations against. The call takes no paging parameters, so one request yields the whole set.
# Run evaluation
Source: https://www.voiceflow.com/docs/api-reference/evaluation/run-evaluation
/specs-prettified/realtime/openapi.stable.json post /v1/stable/evaluation/{evaluationID}/run
Scores one finished conversation against an evaluation. The response carries the verdict together with the reasoning behind it, so a low score says why.
# Update evaluation
Source: https://www.voiceflow.com/docs/api-reference/evaluation/update-evaluation
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/evaluation/{evaluationID}
Changes an existing evaluation in place. The response carries only a confirmation message, so refetch the evaluation to read its new values.
# Create many paths
Source: https://www.voiceflow.com/docs/api-reference/function-path/create-many-paths
/specs-prettified/realtime/openapi.stable.json post /v1/stable/function-path/batch
Adds several function paths to its function in one request, each taking the fields the single-create call takes. The response carries the created function paths in the same shape the list call returns.
# Create path
Source: https://www.voiceflow.com/docs/api-reference/function-path/create-path
/specs-prettified/realtime/openapi.stable.json post /v1/stable/function-path
Adds a function path to its function, one of the named exits a function can return through. The response carries the ID that later calls address it by.
# Delete path
Source: https://www.voiceflow.com/docs/api-reference/function-path/delete-path
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/function-path/{pathID}
Deletes a single function path by ID. A function path is one of the named exits a function can return through. The response carries only a confirmation message, so refetch the function paths to see what is left.
# Get path
Source: https://www.voiceflow.com/docs/api-reference/function-path/get-path
/specs-prettified/realtime/openapi.stable.json get /v1/stable/function-path/{pathID}
Returns a single function path by ID, with the fields that define it. A function path is one of the named exits a function can return through.
# List paths
Source: https://www.voiceflow.com/docs/api-reference/function-path/list-paths
/specs-prettified/realtime/openapi.stable.json get /v1/stable/function-path
Returns every function path in its function. A function path is one of the named exits a function can return through. The call takes no paging parameters, so one request yields the whole set.
# Update path
Source: https://www.voiceflow.com/docs/api-reference/function-path/update-path
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/function-path/{pathID}
Changes an existing function path in place. The response carries only a confirmation message, so refetch the function path to read its new values.
# Create many variables
Source: https://www.voiceflow.com/docs/api-reference/function-variable/create-many-variables
/specs-prettified/realtime/openapi.stable.json post /v1/stable/function-variable/batch
Adds several function variables to its function in one request, each taking the fields the single-create call takes. The response carries the created function variables in the same shape the list call returns.
# Create variable
Source: https://www.voiceflow.com/docs/api-reference/function-variable/create-variable
/specs-prettified/realtime/openapi.stable.json post /v1/stable/function-variable
Adds a function variable to its function, an input or output a function declares. The response carries the ID that later calls address it by.
# Delete variable
Source: https://www.voiceflow.com/docs/api-reference/function-variable/delete-variable
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/function-variable/{variableID}
Deletes a single function variable by ID. A function variable is an input or output a function declares. The response carries only a confirmation message, so refetch the function variables to see what is left.
# Get variable
Source: https://www.voiceflow.com/docs/api-reference/function-variable/get-variable
/specs-prettified/realtime/openapi.stable.json get /v1/stable/function-variable/{variableID}
Returns a single function variable by ID, with the fields that define it. A function variable is an input or output a function declares.
# List variables
Source: https://www.voiceflow.com/docs/api-reference/function-variable/list-variables
/specs-prettified/realtime/openapi.stable.json get /v1/stable/function-variable
Returns every function variable in its function. A function variable is an input or output a function declares. The call takes no paging parameters, so one request yields the whole set.
# Update variable
Source: https://www.voiceflow.com/docs/api-reference/function-variable/update-variable
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/function-variable/{variableID}
Changes an existing function variable in place. The response carries only a confirmation message, so refetch the function variable to read its new values.
# Create function
Source: https://www.voiceflow.com/docs/api-reference/function/create-function
/specs-prettified/realtime/openapi.stable.json post /v1/stable/function
Adds a function to the environment, custom JavaScript that runs in Voiceflow’s sandbox and returns through a named path. The response carries the ID that later calls address it by.
# Create many functions
Source: https://www.voiceflow.com/docs/api-reference/function/create-many-functions
/specs-prettified/realtime/openapi.stable.json post /v1/stable/function/batch
Adds several functions to the environment in one request, each taking the fields the single-create call takes. The response carries the created functions in the same shape the list call returns.
# Delete function
Source: https://www.voiceflow.com/docs/api-reference/function/delete-function
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/function/{functionID}
Deletes a single function by ID. A function is custom JavaScript that runs in Voiceflow’s sandbox and returns through a named path. The response carries only a confirmation message, so refetch the functions to see what is left.
# Get function
Source: https://www.voiceflow.com/docs/api-reference/function/get-function
/specs-prettified/realtime/openapi.stable.json get /v1/stable/function/{functionID}
Returns a single function by ID, with the fields that define it. A function is custom JavaScript that runs in Voiceflow’s sandbox and returns through a named path.
# List functions
Source: https://www.voiceflow.com/docs/api-reference/function/list-functions
/specs-prettified/realtime/openapi.stable.json get /v1/stable/function
Returns every function in the environment. A function is custom JavaScript that runs in Voiceflow’s sandbox and returns through a named path. The call takes no paging parameters, so one request yields the whole set.
# Update function
Source: https://www.voiceflow.com/docs/api-reference/function/update-function
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/function/{functionID}
Changes an existing function in place. The response carries only a confirmation message, so refetch the function to read its new values.
# Query knowledge base
Source: https://www.voiceflow.com/docs/api-reference/knowledge-base/query-knowledge-base
/specs-prettified/realtime/openapi.stable.json post /v1/stable/knowledge-base/query
Searches the knowledge base and returns the passages a retrieval would surface, which is how to see what an agent will be grounded on before it answers.
# Create MCP server
Source: https://www.voiceflow.com/docs/api-reference/mcp-server/create-mcp-server
/specs-prettified/realtime/openapi.stable.json post /v1/stable/mcp-server
Adds a MCP server to the environment, a registered Model Context Protocol server whose tools an agent can call. The response carries the ID that later calls address it by.
# Delete MCP server
Source: https://www.voiceflow.com/docs/api-reference/mcp-server/delete-mcp-server
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/mcp-server/{serverID}
Deletes a single MCP server by ID. A MCP server is a registered Model Context Protocol server whose tools an agent can call. The response carries only a confirmation message, so refetch the MCP servers to see what is left.
# Get MCP server
Source: https://www.voiceflow.com/docs/api-reference/mcp-server/get-mcp-server
/specs-prettified/realtime/openapi.stable.json get /v1/stable/mcp-server/{serverID}
Returns a single MCP server by ID, with the fields that define it. A MCP server is a registered Model Context Protocol server whose tools an agent can call.
# List MCP servers
Source: https://www.voiceflow.com/docs/api-reference/mcp-server/list-mcp-servers
/specs-prettified/realtime/openapi.stable.json get /v1/stable/mcp-server
Returns every MCP server in the environment. A MCP server is a registered Model Context Protocol server whose tools an agent can call. The call takes no paging parameters, so one request yields the whole set.
# Sync MCP server
Source: https://www.voiceflow.com/docs/api-reference/mcp-server/sync-mcp-server
/specs-prettified/realtime/openapi.stable.json put /v1/stable/mcp-server/{serverID}/sync
Refreshes the stored list of tools an MCP server advertises, which is how MCP tools come to exist rather than being created by hand.
# Update MCP server
Source: https://www.voiceflow.com/docs/api-reference/mcp-server/update-mcp-server
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/mcp-server/{serverID}
Changes an existing MCP server in place. The response carries only a confirmation message, so refetch the MCP server to read its new values.
# Get MCP tool
Source: https://www.voiceflow.com/docs/api-reference/mcp-tool/get-mcp-tool
/specs-prettified/realtime/openapi.stable.json get /v1/stable/mcp-tool/{toolID}
Returns a single MCP tool by ID, with the fields that define it. A MCP tool is a tool an MCP server advertises, populated by syncing the server rather than by hand.
# List MCP tools
Source: https://www.voiceflow.com/docs/api-reference/mcp-tool/list-mcp-tools
/specs-prettified/realtime/openapi.stable.json get /v1/stable/mcp-tool
Returns every MCP tool in its server. A MCP tool is a tool an MCP server advertises, populated by syncing the server rather than by hand. The call takes no paging parameters, so one request yields the whole set.
# Create many playbooks
Source: https://www.voiceflow.com/docs/api-reference/playbook/create-many-playbooks
/specs-prettified/realtime/openapi.stable.json post /v1/stable/playbook/batch
Adds several playbooks to the environment in one request, each taking the fields the single-create call takes. The response carries the created playbooks in the same shape the list call returns.
# Create playbook
Source: https://www.voiceflow.com/docs/api-reference/playbook/create-playbook
/specs-prettified/realtime/openapi.stable.json post /v1/stable/playbook
Adds a playbook to the environment, a set of instructions that drives an agent toward a goal, calling tools as it needs them. The response carries the ID that later calls address it by.
# Delete playbook
Source: https://www.voiceflow.com/docs/api-reference/playbook/delete-playbook
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/playbook/{playbookID}
Deletes a single playbook by ID. A playbook is a set of instructions that drives an agent toward a goal, calling tools as it needs them. The response carries only a confirmation message, so refetch the playbooks to see what is left.
# Get playbook
Source: https://www.voiceflow.com/docs/api-reference/playbook/get-playbook
/specs-prettified/realtime/openapi.stable.json get /v1/stable/playbook/{playbookID}
Returns a single playbook by ID, with the fields that define it. A playbook is a set of instructions that drives an agent toward a goal, calling tools as it needs them.
# List playbooks
Source: https://www.voiceflow.com/docs/api-reference/playbook/list-playbooks
/specs-prettified/realtime/openapi.stable.json get /v1/stable/playbook
Returns every playbook in the environment. A playbook is a set of instructions that drives an agent toward a goal, calling tools as it needs them. The call takes no paging parameters, so one request yields the whole set.
# Update playbook
Source: https://www.voiceflow.com/docs/api-reference/playbook/update-playbook
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/playbook/{playbookID}
Changes an existing playbook in place. The response carries only a confirmation message, so refetch the playbook to read its new values.
# Create project
Source: https://www.voiceflow.com/docs/api-reference/project/create-project
/specs-prettified/realtime/openapi.stable.json post /v1/stable/project
Adds a project to the workspace, the container that owns exactly one agent. The response carries the ID that later calls address it by.
# Delete project
Source: https://www.voiceflow.com/docs/api-reference/project/delete-project
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/project/{projectID}
Deletes a single project by ID. A project is the container that owns exactly one agent. The response carries only a confirmation message, so refetch the projects to see what is left.
# Get project
Source: https://www.voiceflow.com/docs/api-reference/project/get-project
/specs-prettified/realtime/openapi.stable.json get /v1/stable/project/{projectID}
Returns a single project by ID, with the fields that define it. A project is the container that owns exactly one agent.
# List projects
Source: https://www.voiceflow.com/docs/api-reference/project/list-projects
/specs-prettified/realtime/openapi.stable.json get /v1/stable/project
Returns every project in the workspace. A project is the container that owns exactly one agent. The call takes no paging parameters, so one request yields the whole set.
# Update project
Source: https://www.voiceflow.com/docs/api-reference/project/update-project
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/project/{projectID}
Changes an existing project in place. The response carries only a confirmation message, so refetch the project to read its new values.
# Your first API request
Source: https://www.voiceflow.com/docs/api-reference/quickstart
Run a real conversation turn against your agent in three curl calls: start a session, launch the conversation, and send a message.
Running a conversation over the API takes two calls: launch the agent, then
send what the user said. A conversation is identified by the `userID` in the
path, so there is no session to create and nothing to thread between calls.
## The recipe
```bash main.sh
#!/usr/bin/env bash
# Recipe: first-conversation-turn
#
# Runs a real conversation against a Voiceflow agent over the REST API: launch
# it, then send a user message, reading the traces returned at each step.
#
# Required environment:
# VF_PAT personal access token (Settings -> Access tokens), vfp_..._...
# VF_PROJECT_ID the project ID (Settings -> General -> Metadata)
set -euo pipefail
: "${VF_PAT:?set VF_PAT to a personal access token from Settings -> Access tokens}"
: "${VF_PROJECT_ID:?set VF_PROJECT_ID to the project ID}"
BASE="https://realtime-api.voiceflow.com/v1/stable"
ENVIRONMENT="${VF_ENVIRONMENT:-main}"
# A conversation is identified by the userID in the path. There is no separate
# session to create: the first call starts one, and later calls with the same
# userID continue it.
USER_ID="cookbook-$(date +%s)"
# The runtime can emit raw control characters inside trace payload strings,
# which strict JSON parsers reject. Strip them before jq.
json() { tr -d '\000-\037'; }
# The runner keys on this prefix to tell a product change (exit 20) from a
# broken script (exit 30). Always route step failures through it.
fail() { echo "FAIL at $1" >&2; exit 1; }
send() {
curl -sf -X PUT "$BASE/conversation/$USER_ID?projectID=$VF_PROJECT_ID&environmentAlias=$ENVIRONMENT" \
-H "Authorization: Bearer $VF_PAT" \
-H "Content-Type: application/json" \
-d "$1"
}
# 1. Launch the conversation. `version` selects the draft or the published
# build of the environment, so the same call can exercise either.
LAUNCH=$(send '{ "action": { "type": "launch" }, "version": "published" }') \
|| fail "launch the conversation (a 401 here means the token is wrong or expired; a 400 saying 'invalid environment tag' means the environmentAlias does not exist on this project)"
printf '%s' "$LAUNCH" | json | jq -e '.traces | length > 0' > /dev/null \
|| fail "launch returned no traces"
# 2. Send a user message to the SAME userID. The agent picks up where the
# launch left off - nothing needs to be threaded through by hand.
REPLY=$(send '{ "action": { "type": "text", "payload": "What can you help me with?" }, "version": "published" }') \
|| fail "send a user message"
printf '%s' "$REPLY" | json | jq -e '.traces | length > 0' > /dev/null \
|| fail "reply returned no traces"
# 3. The agent's words arrive as `text` traces. Assert one came back, so the
# recipe proves a real answer rather than just a 200.
printf '%s' "$REPLY" | json | jq -e '[.traces[] | select(.type == "text")] | length > 0' > /dev/null \
|| fail "reply contained no text trace (a voice agent answers with speak instead)"
echo "ok: launch returned $(printf '%s' "$LAUNCH" | json | jq '.traces | length') trace(s), reply returned $(printf '%s' "$REPLY" | json | jq '.traces | length') trace(s), types: $(printf '%s' "$REPLY" | json | jq -c '[.traces[].type] | unique')"
```
## How it works
- The `userID` in the path IS the conversation. Call the same path again and
the agent picks up where it left off; call it with a new `userID` and you get
a fresh conversation.
- `action` is what the user did. `launch` starts the agent from its entry
point, `text` sends something they typed. The full set is in the
[trace reference](/docs/api-reference/trace-types).
- `version` chooses which build answers: `published` runs the live version of
the environment, `draft` runs what you are currently editing. A project that
has never been published has no published build yet, so use `draft` until
the first publish.
- The response is an array of [traces](/docs/api-reference/trace-types) describing
what the agent did. `text` carries the words a chat agent said; a voice agent
answers with `speak` instead.
- `environmentAlias` names the environment to run. New projects start with
`main`.
## When it fails
| Symptom | Cause | Fix |
| --- | --- | --- |
| `401` | The token is missing, wrong, or expired | Personal access tokens expire, up to a maximum of a year. Create a new one under **Settings** → **Access tokens** |
| `400 invalid environment tag` | The `environmentAlias` does not exist on this project | List the real ones with `GET /v1/stable/environment?projectID=...`. New projects use `main`, not `production` |
| Launch fails or returns nothing on a brand new project | The environment has never been published, so there is no published build to run | Send `"version": "draft"`, which runs what you are editing and works on a fresh project |
| `jq` reports invalid JSON | The runtime emits raw control characters inside trace payload strings | Strip them before parsing, as this recipe does with `tr -d '\000-\037'` |
| Traces come back but none is `text` | The agent replied with audio | A voice agent answers with `speak`; assert on that instead |
# Analytics overview
Source: https://www.voiceflow.com/docs/api-reference/sections/analytics
Query usage and cost: tokens, calls, conversations and unique users, plus the spend attributed to individual functions, playbooks and tools.
Every conversation an agent handles spends tokens, costs money, and exercises
some subset of its playbooks, functions and tools. Analytics turns that into
numbers you can query: scoped to an organization, a workspace or a single
project, and broken down by the component that caused the spend.
## Endpoints
### Analytics query
| Endpoint | Description |
| --- | --- |
| POST [Query call count](/docs/api-reference/analytics/query-call-count) | Query call count for a project. |
| POST [Query call duration](/docs/api-reference/analytics/query-call-duration) | Query real call duration (talk time) for a project. |
| POST [Query workspace transcript count](/docs/api-reference/analytics/query-workspace-transcript-count) | Query transcript count for a workspace. |
| POST [Query project transcript count](/docs/api-reference/analytics/query-project-transcript-count) | Query transcript count for a project. |
| POST [Query transcript cost](/docs/api-reference/analytics/query-transcript-cost) | Query per-interval cost and transcript count for a project. |
| POST [Query workspace interaction count](/docs/api-reference/analytics/query-workspace-interaction-count) | Query interaction count for a workspace. |
| POST [Query project interaction count](/docs/api-reference/analytics/query-project-interaction-count) | Query interaction count for a project. |
| POST [Query organization token usage](/docs/api-reference/analytics/query-organization-token-usage) | Query token usage for an organization. |
| POST [Query workspace token usage](/docs/api-reference/analytics/query-workspace-token-usage) | Query token usage for a workspace. |
| POST [Query project token usage](/docs/api-reference/analytics/query-project-token-usage) | Query token usage for a project. |
| POST [Query hourly organization token usage](/docs/api-reference/analytics/query-hourly-organization-token-usage) | Query hourly token usage for an organization with optional workspace/project filters. |
| POST [Query hourly project token usage](/docs/api-reference/analytics/query-hourly-project-token-usage) | Query timezone-aware hourly token usage for a project. |
| POST [Query daily token usage](/docs/api-reference/analytics/query-daily-token-usage) | Daily breakdown of organization token usage grouped by class and category within a date range. |
| POST [Query entity token usage](/docs/api-reference/analytics/query-entity-token-usage) | Token totals grouped per project and per workspace for an organization. |
| POST [Query category token usage](/docs/api-reference/analytics/query-category-token-usage) | Query timezone-aware hourly token usage for a project grouped by usage category. |
| POST [Query playbook usage](/docs/api-reference/analytics/query-playbook-usage) | Query playbook usage for a project. |
| POST [Query workflow usage](/docs/api-reference/analytics/query-workflow-usage) | Query workflow usage for a project. |
| POST [Query prompt usage](/docs/api-reference/analytics/query-prompt-usage) | Query prompt usage for a project. |
| POST [Query intent usage](/docs/api-reference/analytics/query-intent-usage) | Query intent usage for a project. |
| POST [Query function usage](/docs/api-reference/analytics/query-function-usage) | Query function usage for a project. |
| POST [Query API tool usage](/docs/api-reference/analytics/query-api-tool-usage) | Query API tool usage for a project. |
| POST [Query MCP tool usage](/docs/api-reference/analytics/query-mcp-tool-usage) | Query MCP tool usage for a project. |
| POST [Query knowledge base document usage](/docs/api-reference/analytics/query-knowledge-base-document-usage) | Query knowledge base document usage for a project. |
| POST [Query integration usage](/docs/api-reference/analytics/query-integration-usage) | Query integration usage for a project. |
| POST [Query unique user count](/docs/api-reference/analytics/query-unique-user-count) | Query unique users for a project. |
## Every query has a scope
Analytics endpoints end in the level they measure, and the level is part of the
path:
```text
/v1/stable/analytics/query/token-usage/organization/{organizationID}
/v1/stable/analytics/query/token-usage/workspace/{workspaceID}
/v1/stable/analytics/query/token-usage/project/{projectID}
```
Not every metric exists at every level, which is itself informative: interaction
counts are project and workspace, entity token usage is organization only.
## What you can measure
- **Spend** - token usage overall, by hour, by day, by category, and by entity;
plus transcript cost.
- **Volume** - interactions, transcripts, unique users, call count and call
duration.
- **Where it goes** - usage attributed to functions, playbooks, workflows,
intents, prompts, integrations, API tools, MCP tools and knowledge base
documents.
That last group is the one most people skip. It answers which parts of an agent
are actually costing money, rather than what the agent cost in total.
## Sending a query
Each query takes a request body describing the window and grouping you want, so
they are `POST` rather than `GET` despite being reads.
## What analytics does not return
Analytics returns numbers about conversations, never the conversations
themselves. To read what was actually said, use
[Observe](/docs/api-reference/sections/observe).
# Build overview
Source: https://www.voiceflow.com/docs/api-reference/sections/build
Create and manage the pieces an agent is built from: playbooks, functions, tools, API tools, MCP servers, variables and knowledge base documents.
An agent is assembled from parts: a playbook and the tools it can call, a
function with its branches and variables, an API tool, an MCP server, the
project's variables, and the documents its knowledge base retrieves from.
All of them can be created and changed from outside the Studio, which is what
makes generating agents from a template, importing them from another system, or
keeping a set of projects consistent with each other possible.
## Endpoints
### Agent
| Endpoint | Description |
| --- | --- |
| GET [Get agent](/docs/api-reference/agent/get-agent) | Get agent configuration. |
| PATCH [Update agent](/docs/api-reference/agent/update-agent) | Update agent configuration. |
### Playbook
| Endpoint | Description |
| --- | --- |
| GET [List playbooks](/docs/api-reference/playbook/list-playbooks) | List all playbooks by project ID. |
| POST [Create playbook](/docs/api-reference/playbook/create-playbook) | Create a new playbook. |
| POST [Create many playbooks](/docs/api-reference/playbook/create-many-playbooks) | Create multiple new playbooks. |
| GET [Get playbook](/docs/api-reference/playbook/get-playbook) | Get a playbook by ID. |
| PATCH [Update playbook](/docs/api-reference/playbook/update-playbook) | Update a playbook by ID. |
| DELETE [Delete playbook](/docs/api-reference/playbook/delete-playbook) | Delete a playbook by ID. |
### Function
| Endpoint | Description |
| --- | --- |
| GET [List functions](/docs/api-reference/function/list-functions) | List all functions by project ID. |
| POST [Create function](/docs/api-reference/function/create-function) | Create a new function. |
| POST [Create many functions](/docs/api-reference/function/create-many-functions) | Create multiple new functions. |
| GET [Get function](/docs/api-reference/function/get-function) | Get a function by ID. |
| PATCH [Update function](/docs/api-reference/function/update-function) | Update a function by ID. |
| DELETE [Delete function](/docs/api-reference/function/delete-function) | Delete a function by ID. |
### Function path
| Endpoint | Description |
| --- | --- |
| GET [List paths](/docs/api-reference/function-path/list-paths) | List all paths by function ID. |
| POST [Create path](/docs/api-reference/function-path/create-path) | Create a new path. |
| POST [Create many paths](/docs/api-reference/function-path/create-many-paths) | Create multiple new paths. |
| GET [Get path](/docs/api-reference/function-path/get-path) | Get a path by ID. |
| PATCH [Update path](/docs/api-reference/function-path/update-path) | Update a path by ID. |
| DELETE [Delete path](/docs/api-reference/function-path/delete-path) | Delete a path by ID. |
### Function variable
| Endpoint | Description |
| --- | --- |
| GET [List variables](/docs/api-reference/function-variable/list-variables) | List all variables by function ID. |
| POST [Create variable](/docs/api-reference/function-variable/create-variable) | Create a new variable. |
| POST [Create many variables](/docs/api-reference/function-variable/create-many-variables) | Create multiple new variables. |
| GET [Get variable](/docs/api-reference/function-variable/get-variable) | Get a variable by ID. |
| PATCH [Update variable](/docs/api-reference/function-variable/update-variable) | Update a variable by ID. |
| DELETE [Delete variable](/docs/api-reference/function-variable/delete-variable) | Delete a variable by ID. |
### Tool
| Endpoint | Description |
| --- | --- |
| GET [List tools](/docs/api-reference/tool/list-tools) | List all tools for the agent or a specific playbook. |
| POST [Create tool](/docs/api-reference/tool/create-tool) | Create a new tool. |
| POST [Create many tools](/docs/api-reference/tool/create-many-tools) | Create multiple new tools. |
| GET [Get tool](/docs/api-reference/tool/get-tool) | Get a tool by ID. |
| PATCH [Update tool](/docs/api-reference/tool/update-tool) | Update a tool by ID. |
| DELETE [Delete tool](/docs/api-reference/tool/delete-tool) | Delete a tool by ID. |
### API tool
| Endpoint | Description |
| --- | --- |
| GET [List API tools](/docs/api-reference/api-tool/list-api-tools) | List all API tools by project ID. |
| POST [Create API tool](/docs/api-reference/api-tool/create-api-tool) | Create a new API tool. |
| POST [Create many API tools](/docs/api-reference/api-tool/create-many-api-tools) | Create multiple new API tools. |
| GET [Get API tool](/docs/api-reference/api-tool/get-api-tool) | Get an API tool by ID. |
| PATCH [Update API tool](/docs/api-reference/api-tool/update-api-tool) | Update an API tool by ID. |
| DELETE [Delete API tool](/docs/api-reference/api-tool/delete-api-tool) | Delete an API tool by ID. |
### API tool variable
| Endpoint | Description |
| --- | --- |
| GET [List variables](/docs/api-reference/api-tool-variable/list-variables) | List all variables by API tool ID. |
| POST [Create variable](/docs/api-reference/api-tool-variable/create-variable) | Create a new variable. |
| POST [Create many variables](/docs/api-reference/api-tool-variable/create-many-variables) | Create multiple new variables. |
| GET [Get variable](/docs/api-reference/api-tool-variable/get-variable) | Get an variable by ID. |
| PATCH [Update variable](/docs/api-reference/api-tool-variable/update-variable) | Update an variable by ID. |
| DELETE [Delete variable](/docs/api-reference/api-tool-variable/delete-variable) | Delete an variable by ID. |
### Variable
| Endpoint | Description |
| --- | --- |
| GET [List variables](/docs/api-reference/variable/list-variables) | List all variables by project ID. |
| POST [Create variable](/docs/api-reference/variable/create-variable) | Create a new variable. |
| POST [Create many variables](/docs/api-reference/variable/create-many-variables) | Create multiple new variables. |
| GET [Get variable](/docs/api-reference/variable/get-variable) | Get a variable by ID. |
| PATCH [Update variable](/docs/api-reference/variable/update-variable) | Update a variable by ID. |
| DELETE [Delete variable](/docs/api-reference/variable/delete-variable) | Delete a variable by ID. |
### MCP server
| Endpoint | Description |
| --- | --- |
| GET [List MCP servers](/docs/api-reference/mcp-server/list-mcp-servers) | List all MCP servers by project ID. |
| POST [Create MCP server](/docs/api-reference/mcp-server/create-mcp-server) | Create a new MCP server. |
| GET [Get MCP server](/docs/api-reference/mcp-server/get-mcp-server) | Get an MCP server by ID. |
| PATCH [Update MCP server](/docs/api-reference/mcp-server/update-mcp-server) | Update an MCP server by ID. |
| DELETE [Delete MCP server](/docs/api-reference/mcp-server/delete-mcp-server) | Delete an MCP server by ID. |
| PUT [Sync MCP server](/docs/api-reference/mcp-server/sync-mcp-server) | Sync tool changes for an MCP server by ID. |
### MCP tool
| Endpoint | Description |
| --- | --- |
| GET [List MCP tools](/docs/api-reference/mcp-tool/list-mcp-tools) | List all MCP tools by project ID. |
| GET [Get MCP tool](/docs/api-reference/mcp-tool/get-mcp-tool) | Get an MCP tool by ID. |
### Knowledge base document
| Endpoint | Description |
| --- | --- |
| GET [List documents](/docs/api-reference/document/list-documents) | List all documents by project ID. |
| POST [Create URL document](/docs/api-reference/document/create-url-document) | Create a new document from a URL. |
| POST [Create text document](/docs/api-reference/document/create-text-document) | Create a new document from raw text. |
| POST [Create table document](/docs/api-reference/document/create-table-document) | Create a new document from structured data. |
| GET [Get document](/docs/api-reference/document/get-document) | Get a document by ID. |
| PATCH [Update document](/docs/api-reference/document/update-document) | Update a document by ID. |
| DELETE [Delete document](/docs/api-reference/document/delete-document) | Delete a document by ID. |
## How the build endpoints are shaped
Every resource follows the same six-verb pattern, so learning one teaches the
rest:
| Verb | Path | Purpose |
| --- | --- | --- |
| `GET` | `/{resource}` | list everything in the project |
| `POST` | `/{resource}` | create one |
| `POST` | `/{resource}/batch` | create many in a single call |
| `GET` | `/{resource}/{id}` | fetch one |
| `PATCH` | `/{resource}/{id}` | change part of one |
| `DELETE` | `/{resource}/{id}` | remove one |
The `batch` variant matters when you are importing. Creating fifty variables
one call at a time is fifty round trips and fifty chances to end up half
migrated; one batch call is atomic from your side.
## Scoping every call
Build endpoints act inside one environment of one project, so both are
required query parameters:
```bash
curl "https://realtime-api.voiceflow.com/v1/stable/function?projectID=$VF_PROJECT_ID&environmentAlias=main" \
-H "Authorization: Bearer $VF_PAT"
```
Editing `main` changes what your team sees in the Creator. To stage changes
without touching it, clone an environment first, build against the clone, and
[merge](/docs/api-reference/environment/merge-environments) when you are satisfied.
## How the pieces relate
- A **playbook** is the unit of agent behaviour. It holds instructions and the
tools it may call.
- **Tools** are what a playbook can do. An **API tool** calls an HTTP endpoint;
a **function** runs your own code; an **MCP server** contributes a set of
**MCP tools** discovered from that server.
- **Function paths** are the branches a function can exit through, and
**function variables** are its inputs and outputs. Both belong to a function
and are managed separately, so you can add a branch without rewriting the
function.
- **Variables** are project state that persists across a conversation.
- **Knowledge base documents** are the corpus the agent retrieves from. Create
them from a URL, from text, or by uploading a table.
## Where to go next
Once an agent is built, [publish it](/docs/api-reference/sections/publishing) to make
the changes live, and [run a conversation](/docs/api-reference/sections/running-agents) against
it to see how it behaves.
# Insights overview
Source: https://www.voiceflow.com/docs/api-reference/sections/insights
Score conversations against criteria you define, so agent quality becomes a number you can track over time instead of a sample you skim.
An evaluation is a set of criteria you define and then run against
conversations that already happened. It turns "is the agent doing a good job"
into a score you can watch over time, rather than a handful of transcripts
somebody read on a Friday.
## Endpoints
### Evaluation
| Endpoint | Description |
| --- | --- |
| GET [List evaluations](/docs/api-reference/evaluation/list-evaluations) | List all evaluations by project ID. |
| POST [Create evaluation](/docs/api-reference/evaluation/create-evaluation) | Create a new evaluation. |
| GET [Get evaluation](/docs/api-reference/evaluation/get-evaluation) | Get an evaluation by ID. |
| PATCH [Update evaluation](/docs/api-reference/evaluation/update-evaluation) | Update an evaluation by ID. |
| DELETE [Delete evaluation](/docs/api-reference/evaluation/delete-evaluation) | Delete an evaluation by ID. |
| POST [Run evaluation](/docs/api-reference/evaluation/run-evaluation) | Run an evaluation. |
## The shape
An **evaluation** is a definition: what you are measuring and how. Creating one
does not score anything by itself. Running it applies it and produces a result.
```bash
curl -X POST "https://realtime-api.voiceflow.com/v1/stable/evaluation/$EVALUATION_ID/run" \
-H "Authorization: Bearer $VF_PAT"
```
That split is deliberate. The definition is stable and version-controlled by
you; runs accumulate against it, so a score means something over time rather
than being a one-off measurement with its own private criteria.
## Evaluations and transcripts
Evaluations score conversations that already happened, which makes
[Observe](/docs/api-reference/sections/observe) the source of what they measure.
Search for the transcripts you care about, then evaluate that set.
## How this differs from automated testing
Evaluations judge real conversations after the fact.
[QA](/docs/api-reference/sections/qa) does the opposite: it replays scripted
conversations you wrote, and asserts the agent still answers the way you
decided it should. Use evaluations to find out what is happening in production,
and QA to stop a change breaking what already worked.
## Where to go next
Once you know what to look for, encode it as a [test](/docs/api-reference/sections/qa)
so a regression fails loudly instead of showing up in next month's numbers.
# Manage overview
Source: https://www.voiceflow.com/docs/api-reference/sections/manage
Create and administer the containers your agents live in: workspaces that group projects and people, and projects that each own a single agent.
Workspaces group projects and the people who can reach them. A project owns a
single agent and everything inside it.
These endpoints create and administer both, and they are where you get the
`projectID` that almost every other endpoint in this API asks for.
## Endpoints
### Project
| Endpoint | Description |
| --- | --- |
| GET [List projects](/docs/api-reference/project/list-projects) | List all projects by workspace ID. |
| POST [Create project](/docs/api-reference/project/create-project) | Create a new project. |
| GET [Get project](/docs/api-reference/project/get-project) | Get a project by ID. |
| PATCH [Update project](/docs/api-reference/project/update-project) | Update a project by ID. |
| DELETE [Delete project](/docs/api-reference/project/delete-project) | Delete a project by ID. |
### Workspace
| Endpoint | Description |
| --- | --- |
| GET [List workspaces](/docs/api-reference/workspace/list-workspaces) | List all workspaces the authorized account is a member of. |
| POST [Create workspace](/docs/api-reference/workspace/create-workspace) | Create a new workspace. |
| GET [Get workspace](/docs/api-reference/workspace/get-workspace) | Get a single workspace by ID. |
| PATCH [Update workspace](/docs/api-reference/workspace/update-workspace) | Update a single workspace by ID. |
| DELETE [Delete workspace](/docs/api-reference/workspace/delete-workspace) | Delete a single workspace by ID. |
## The hierarchy
An organization contains **workspaces**. A workspace contains **projects**. A
project owns exactly one agent, along with its playbooks, tools, variables,
knowledge base and environments.
Most other endpoints in this API take a `projectID`, which you get by listing
the projects in a workspace:
```bash
curl "https://realtime-api.voiceflow.com/v1/stable/project?workspaceID=$VF_WORKSPACE_ID" \
-H "Authorization: Bearer $VF_PAT"
```
## What a token can see
A [personal access token](/docs/api-reference/authentication) carries your own
access. Listing workspaces returns every workspace your account belongs to, not
a subset scoped to the integration, so a script that iterates workspaces will
reach further than you might expect. Pin the IDs you mean to operate on rather
than discovering them at runtime.
## Deleting
Deleting a project removes the agent and everything in it, including
transcripts. Deleting a workspace removes every project inside it. Neither is
recoverable through the API.
## Where to go next
With a project in hand, [build its agent](/docs/api-reference/sections/build) and
[ship it through environments](/docs/api-reference/sections/publishing).
# Observe overview
Source: https://www.voiceflow.com/docs/api-reference/sections/observe
Read the conversations your agent actually had. Search transcripts, fetch a single one, and attach your own properties to record what happened.
Every conversation your agent has is kept as a transcript. These endpoints let
you search them, read an individual one turn by turn, and attach your own
fields to record things the runtime cannot know, such as whether the
conversation was escalated or how it ended.
## Endpoints
### Transcript
| Endpoint | Description |
| --- | --- |
| POST [Search transcripts](/docs/api-reference/transcript/search-transcripts) | Search transcripts by project ID. |
| GET [Get transcript](/docs/api-reference/transcript/get-transcript) | Get a transcript by ID. |
### Transcript property
| Endpoint | Description |
| --- | --- |
| GET [List properties](/docs/api-reference/transcript-property/list-properties) | List all properties by project ID. |
| POST [Create property](/docs/api-reference/transcript-property/create-property) | Create a new property. |
| GET [Get property](/docs/api-reference/transcript-property/get-property) | Get property by ID. |
| PATCH [Update property](/docs/api-reference/transcript-property/update-property) | Update a property by ID. |
| DELETE [Delete property](/docs/api-reference/transcript-property/delete-property) | Delete a property by ID. |
| PUT [Set property value](/docs/api-reference/transcript-property/set-property-value) | Set a property value on a transcript. |
## Finding conversations
Transcript search is a `POST` rather than a `GET`, because the filters are rich
enough to need a body:
```bash
curl -X POST "https://realtime-api.voiceflow.com/v1/stable/transcript/search" \
-H "Authorization: Bearer $VF_PAT" \
-H "Content-Type: application/json" \
-d '{ "projectID": "'"$VF_PROJECT_ID"'" }'
```
Fetching a single transcript by ID returns its turns, so a common shape is
search for the conversations you care about, then fetch each one.
## Properties are your own metadata
A **transcript property** is a field you define on the project, and a property
value is that field set on one transcript. Use them to record things the runtime
cannot know: whether the conversation was escalated, which experiment a user was
in, what the outcome was.
Define the property once, then set its value per transcript. Because properties
are project-level, they also become the vocabulary you filter searches by.
## What transcripts are not for
Transcript endpoints return conversations, not counts. If you want totals,
costs, or usage over time, that is
[Analytics](/docs/api-reference/sections/analytics). If you want quality scored
against criteria, that is [Insights](/docs/api-reference/sections/insights).
## Where to go next
Transcripts are the input to [evaluations](/docs/api-reference/sections/insights) -
you can run an evaluation over conversations that already happened.
# Publishing overview
Source: https://www.voiceflow.com/docs/api-reference/sections/publishing
Ship changes with environments. Edit a draft, publish it live, clone one to work in isolation, merge it back, and split traffic between versions.
An environment is a copy of your agent with its own draft and its own live
version. Publishing promotes the draft; until you do, nothing you change
reaches users.
These endpoints let you work in an environment of your own, merge it back when
it is ready, and route a share of real traffic to it to compare two versions
against each other.
## Endpoints
### Environment
| Endpoint | Description |
| --- | --- |
| GET [List environments](/docs/api-reference/environment/list-environments) | List all environments by project ID. |
| PUT [Merge environments](/docs/api-reference/environment/merge-environments) | Merge one environment into another. |
| PUT [Update traffic split](/docs/api-reference/environment/update-traffic-split) | Update the percentage of traffic routed to each environment. |
| GET [Get environment](/docs/api-reference/environment/get-environment) | Get an environment by alias or ID. |
| PATCH [Update environment](/docs/api-reference/environment/update-environment) | Update a environment by alias or ID. |
| DELETE [Delete environment](/docs/api-reference/environment/delete-environment) | Delete an environment by alias or ID. |
| GET [Export environment](/docs/api-reference/environment/export-environment) | Export all data from environment. |
| PUT [Compile environment](/docs/api-reference/environment/compile-environment) | Compile an environment. |
| POST [Clone environment](/docs/api-reference/environment/clone-environment) | Clone an environment. |
| POST [Publish environment](/docs/api-reference/environment/publish-environment) | Publish live version of an environment. |
## Draft and published
Every environment holds two versions of the agent. The **draft** is what you
edit and what `version: "draft"` runs when you
[send a conversation](/docs/api-reference/sections/running-agents). The **published** version is
what real traffic reaches. Publishing promotes the draft to published; nothing
you change before that is visible to users.
New projects start with a single environment called `main`. Passing an alias
the project does not have returns `400 invalid environment tag`, so list them
first if you are not sure:
```bash
curl "https://realtime-api.voiceflow.com/v1/stable/environment?projectID=$VF_PROJECT_ID" \
-H "Authorization: Bearer $VF_PAT"
```
## Working with more than one
- **Clone** copies an existing environment into a new one. This is how you get
a second environment to build against without touching `main`.
- **Merge** folds one environment's changes back into another.
- **Publish** promotes an environment's draft to its published version.
- **Update traffic split** routes a share of live conversations to a different
environment, which is how you run one version against another on real
traffic.
- **Export** returns the environment as JSON, for backup or for inspecting a
build outside Voiceflow.
- **Compile** builds the environment without publishing it, so you can surface
errors before users would.
## Secrets
Secret values are environment-scoped, so the same secret name can hold a test
value in one environment and a production value in another. They are not
managed through the environment endpoints today.
## Where to go next
After publishing, [watch what happens](/docs/api-reference/sections/observe) in the
transcripts, and [measure it](/docs/api-reference/sections/insights).
# QA overview
Source: https://www.voiceflow.com/docs/api-reference/sections/qa
Replay scripted conversations against your agent and assert what it does, so a change that breaks a scenario fails loudly instead of silently.
A test is a conversation you have written down, together with the assertions
that must hold when it runs. Execute it after a change and a broken scenario
fails immediately, instead of surfacing later in production.
## Endpoints
### Test
| Endpoint | Description |
| --- | --- |
| GET [List tests](/docs/api-reference/test/list-tests) | List all tests by project ID. |
| POST [Create test](/docs/api-reference/test/create-test) | Create a new test. |
| POST [Create many tests](/docs/api-reference/test/create-many-tests) | Create multiple new tests. |
| GET [Get test](/docs/api-reference/test/get-test) | Get a test by ID. |
| PATCH [Update test](/docs/api-reference/test/update-test) | Update a test by ID. |
| DELETE [Delete test](/docs/api-reference/test/delete-test) | Delete a test by ID. |
### Test turn
| Endpoint | Description |
| --- | --- |
| GET [List turns](/docs/api-reference/test-turn/list-turns) | List all turns by test ID. |
| POST [Create turn](/docs/api-reference/test-turn/create-turn) | Create a new turn. |
| POST [Create many turns](/docs/api-reference/test-turn/create-many-turns) | Create multiple new turns. |
| GET [Get turn](/docs/api-reference/test-turn/get-turn) | Get a turn by ID. |
| PATCH [Update turn](/docs/api-reference/test-turn/update-turn) | Update a turn by ID. |
| DELETE [Delete turn](/docs/api-reference/test-turn/delete-turn) | Delete a turn by ID. |
### Test check
| Endpoint | Description |
| --- | --- |
| GET [List checks](/docs/api-reference/test-check/list-checks) | List all checks by turn ID. |
| POST [Create check](/docs/api-reference/test-check/create-check) | Create a new check. |
| POST [Create many checks](/docs/api-reference/test-check/create-many-checks) | Create multiple new checks. |
| GET [Get check](/docs/api-reference/test-check/get-check) | Get a check by ID. |
| PATCH [Update check](/docs/api-reference/test-check/update-check) | Update a check by ID. |
| DELETE [Delete check](/docs/api-reference/test-check/delete-check) | Delete a check by ID. |
### Test run
| Endpoint | Description |
| --- | --- |
| POST [Search runs](/docs/api-reference/test-run/search-runs) | Search runs by project ID. |
| POST [Create run](/docs/api-reference/test-run/create-run) | Create a new run. |
| POST [Create many runs](/docs/api-reference/test-run/create-many-runs) | Create multiple new runs. |
| GET [Get run](/docs/api-reference/test-run/get-run) | Get a run by ID. |
## Four resources, one idea
| Resource | What it is |
| --- | --- |
| **Test** | the scenario: a named conversation you want to keep working |
| **Test turn** | one exchange inside it, in order |
| **Test check** | an assertion about what the agent should do |
| **Test run** | one execution of a test, and its result |
A test is the container. Turns are the script. Checks are what must be true.
Runs are what happened each time you executed it.
Turns and checks are managed independently of the test, so you can add a check
to an existing scenario without rewriting the conversation, or extend the
conversation without touching the assertions.
## Creating a suite
Each resource has a `batch` endpoint, which is what you want when defining a
suite from a file rather than clicking through it:
```bash
curl -X POST "https://realtime-api.voiceflow.com/v1/stable/test/batch?projectID=$VF_PROJECT_ID&environmentAlias=main" \
-H "Authorization: Bearer $VF_PAT" \
-H "Content-Type: application/json" \
-d '{ "data": [ ... ] }'
```
## Reading results
Runs are searchable rather than merely listable, so the useful question is not
"what ran" but "what failed, and since when". Search runs, then fetch the ones
you care about.
## How this differs from evaluations
These are different jobs and it is worth keeping them apart.
QA replays conversations *you* wrote and fails when the agent stops behaving as
decided. [Insights](/docs/api-reference/sections/insights) scores conversations *real
users* had, and tells you how it is going. One protects against regressions; the
other finds things you did not think to test.
## Where to go next
Run tests against a cloned [environment](/docs/api-reference/sections/publishing)
before merging into `main`, so a failing check blocks the change rather than
reporting on it afterwards.
# Running agents overview
Source: https://www.voiceflow.com/docs/api-reference/sections/running-agents
Run conversations against an agent over HTTP. Send what a user would say, read the traces that come back, and inspect or reset the state between turns.
A conversation is the agent doing its job: a user says something, the agent
decides what to do, and everything it did comes back as typed events.
Driving that from your own code is how you put the agent behind a different
interface, or check how a change behaves before anyone else sees it.
Conversation state sits alongside, so you can read what the agent currently
believes, change a variable mid-turn, or start over.
## Endpoints
### Conversation
| Endpoint | Description |
| --- | --- |
| PUT [Send](/docs/api-reference/conversation/send) | Send message to a conversation. |
### Conversation state
| Endpoint | Description |
| --- | --- |
| GET [Get state](/docs/api-reference/conversation-state/get-state) | Get conversation state for a user. |
| PATCH [Update state](/docs/api-reference/conversation-state/update-state) | Update conversation state for a user. |
| DELETE [Delete state](/docs/api-reference/conversation-state/delete-state) | Delete conversation state for a user. |
| PATCH [Update variables](/docs/api-reference/conversation-state/update-variables) | Updates variables in the conversation state by merging with the properties in the request body. |
### Knowledge base query
| Endpoint | Description |
| --- | --- |
| POST [Query knowledge base](/docs/api-reference/knowledge-base/query-knowledge-base) | Execute a query against documents in the knowledge base. |
## A conversation is a userID
There is no session to create. The `userID` in the path *is* the conversation:
call the same path again and the agent continues where it left off, call it
with a new `userID` and you get a fresh one.
```bash
curl -X PUT "https://realtime-api.voiceflow.com/v1/stable/conversation/user-123?projectID=$VF_PROJECT_ID&environmentAlias=main" \
-H "Authorization: Bearer $VF_PAT" \
-H "Content-Type: application/json" \
-d '{ "action": { "type": "launch" }, "version": "published" }'
```
That returns an array of [traces](/docs/api-reference/trace-types) describing
everything the agent did in response.
## The two fields that matter
`action` is what the user did. `launch` starts the agent from its entry point;
`text` sends something they typed:
```json
{ "action": { "type": "text", "payload": "What can you help me with?" }, "version": "published" }
```
`version` chooses which build answers. `published` runs the live version of the
environment; `draft` runs what you are currently editing, which is what you want
while testing a change.
## Reading the response
The agent's output is a list of traces, not a single message. A chat agent's
words arrive as `text` traces; a voice agent answers with `speak`. Buttons,
cards, carousels and debug output each have their own type, and the
[trace reference](/docs/api-reference/trace-types) documents every one.
Two things worth handling from the start:
- Iterate the traces rather than taking the first. A single turn routinely
returns a message, then buttons, then debug output.
- Strip control characters before parsing. The runtime can emit raw control
characters inside trace payload strings, which strict JSON parsers reject.
## Conversation state
The state endpoints let you inspect what the agent currently believes, change a
variable mid-conversation, or delete the state to start over without changing
the `userID`.
## Where to go next
The [first conversation turn](/docs/cookbook/first-conversation-turn) recipe is this
flow as a script you can run, verified against a live agent.
# Create check
Source: https://www.voiceflow.com/docs/api-reference/test-check/create-check
/specs-prettified/realtime/openapi.stable.json post /v1/stable/test-check
Adds a test check to its turn, one assertion about an agent turn, comparing the reply or the behaviour behind it. The response carries the ID that later calls address it by.
# Create many checks
Source: https://www.voiceflow.com/docs/api-reference/test-check/create-many-checks
/specs-prettified/realtime/openapi.stable.json post /v1/stable/test-check/batch
Adds several test checks to its turn in one request, each taking the fields the single-create call takes. The response carries the created test checks in the same shape the list call returns.
# Delete check
Source: https://www.voiceflow.com/docs/api-reference/test-check/delete-check
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/test-check/{checkID}
Deletes a single test check by ID. A test check is one assertion about an agent turn, comparing the reply or the behaviour behind it. The response carries only a confirmation message, so refetch the test checks to see what is left.
# Get check
Source: https://www.voiceflow.com/docs/api-reference/test-check/get-check
/specs-prettified/realtime/openapi.stable.json get /v1/stable/test-check/{checkID}
Returns a single test check by ID, with the fields that define it. A test check is one assertion about an agent turn, comparing the reply or the behaviour behind it.
# List checks
Source: https://www.voiceflow.com/docs/api-reference/test-check/list-checks
/specs-prettified/realtime/openapi.stable.json get /v1/stable/test-check
Returns every test check in its turn. A test check is one assertion about an agent turn, comparing the reply or the behaviour behind it. The call takes no paging parameters, so one request yields the whole set.
# Update check
Source: https://www.voiceflow.com/docs/api-reference/test-check/update-check
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/test-check/{checkID}
Changes an existing test check in place. The response carries only a confirmation message, so refetch the test check to read its new values.
# Create many runs
Source: https://www.voiceflow.com/docs/api-reference/test-run/create-many-runs
/specs-prettified/realtime/openapi.stable.json post /v1/stable/test-run/batch
Adds several test runs to the environment in one request, each taking the fields the single-create call takes. The response carries the created test runs in the same shape the list call returns.
# Create run
Source: https://www.voiceflow.com/docs/api-reference/test-run/create-run
/specs-prettified/realtime/openapi.stable.json post /v1/stable/test-run
Adds a test run to the environment, one execution of a test, carrying how many of its checks passed. The response carries the ID that later calls address it by.
# Get run
Source: https://www.voiceflow.com/docs/api-reference/test-run/get-run
/specs-prettified/realtime/openapi.stable.json get /v1/stable/test-run/{runID}
Returns a single test run by ID, with the fields that define it. A test run is one execution of a test, carrying how many of its checks passed.
# Search runs
Source: https://www.voiceflow.com/docs/api-reference/test-run/search-runs
/specs-prettified/realtime/openapi.stable.json post /v1/stable/test-run/search
Finds past runs of a test, each carrying how many of its checks passed. The body takes `take` and `skip`, so results arrive a page at a time rather than all at once.
# Create many turns
Source: https://www.voiceflow.com/docs/api-reference/test-turn/create-many-turns
/specs-prettified/realtime/openapi.stable.json post /v1/stable/test-turn/batch
Adds several test turns to its test in one request, each taking the fields the single-create call takes. The response carries the created test turns in the same shape the list call returns.
# Create turn
Source: https://www.voiceflow.com/docs/api-reference/test-turn/create-turn
/specs-prettified/realtime/openapi.stable.json post /v1/stable/test-turn
Adds a test turn to its test, one side of a scripted conversation, either what the user says or the agent reply the checks assert on. The response carries the ID that later calls address it by.
# Delete turn
Source: https://www.voiceflow.com/docs/api-reference/test-turn/delete-turn
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/test-turn/{turnID}
Deletes a single test turn by ID. A test turn is one side of a scripted conversation, either what the user says or the agent reply the checks assert on. The response carries only a confirmation message, so refetch the test turns to see what is left.
# Get turn
Source: https://www.voiceflow.com/docs/api-reference/test-turn/get-turn
/specs-prettified/realtime/openapi.stable.json get /v1/stable/test-turn/{turnID}
Returns a single test turn by ID, with the fields that define it. A test turn is one side of a scripted conversation, either what the user says or the agent reply the checks assert on.
# List turns
Source: https://www.voiceflow.com/docs/api-reference/test-turn/list-turns
/specs-prettified/realtime/openapi.stable.json get /v1/stable/test-turn
Returns every test turn in its test. A test turn is one side of a scripted conversation, either what the user says or the agent reply the checks assert on. The call takes no paging parameters, so one request yields the whole set.
# Update turn
Source: https://www.voiceflow.com/docs/api-reference/test-turn/update-turn
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/test-turn/{turnID}
Changes an existing test turn in place. The response carries only a confirmation message, so refetch the test turn to read its new values.
# Create many tests
Source: https://www.voiceflow.com/docs/api-reference/test/create-many-tests
/specs-prettified/realtime/openapi.stable.json post /v1/stable/test/batch
Adds several tests to the environment in one request, each taking the fields the single-create call takes. The response carries the created tests in the same shape the list call returns.
# Create test
Source: https://www.voiceflow.com/docs/api-reference/test/create-test
/specs-prettified/realtime/openapi.stable.json post /v1/stable/test
Adds a test to the environment, a scripted conversation replayed against the agent. The response carries the ID that later calls address it by.
# Delete test
Source: https://www.voiceflow.com/docs/api-reference/test/delete-test
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/test/{testID}
Deletes a single test by ID. A test is a scripted conversation replayed against the agent. The response carries only a confirmation message, so refetch the tests to see what is left.
# Get test
Source: https://www.voiceflow.com/docs/api-reference/test/get-test
/specs-prettified/realtime/openapi.stable.json get /v1/stable/test/{testID}
Returns a single test by ID, with the fields that define it. A test is a scripted conversation replayed against the agent.
# List tests
Source: https://www.voiceflow.com/docs/api-reference/test/list-tests
/specs-prettified/realtime/openapi.stable.json get /v1/stable/test
Returns every test in the environment. A test is a scripted conversation replayed against the agent. The call takes no paging parameters, so one request yields the whole set.
# Update test
Source: https://www.voiceflow.com/docs/api-reference/test/update-test
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/test/{testID}
Changes an existing test in place. The response carries only a confirmation message, so refetch the test to read its new values.
# Create many tools
Source: https://www.voiceflow.com/docs/api-reference/tool/create-many-tools
/specs-prettified/realtime/openapi.stable.json post /v1/stable/tool/batch
Adds several tools to the environment in one request, each taking the fields the single-create call takes. The response carries the created tools in the same shape the list call returns.
# Create tool
Source: https://www.voiceflow.com/docs/api-reference/tool/create-tool
/specs-prettified/realtime/openapi.stable.json post /v1/stable/tool
Adds a tool to the environment, something a playbook can call during a conversation. The response carries the ID that later calls address it by.
# Delete tool
Source: https://www.voiceflow.com/docs/api-reference/tool/delete-tool
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/tool/{toolID}
Deletes a single tool by ID. A tool is something a playbook can call during a conversation. The response carries only a confirmation message, so refetch the tools to see what is left.
# Get tool
Source: https://www.voiceflow.com/docs/api-reference/tool/get-tool
/specs-prettified/realtime/openapi.stable.json get /v1/stable/tool/{toolID}
Returns a single tool by ID, with the fields that define it. A tool is something a playbook can call during a conversation.
# List tools
Source: https://www.voiceflow.com/docs/api-reference/tool/list-tools
/specs-prettified/realtime/openapi.stable.json get /v1/stable/tool
Returns every tool in the environment. A tool is something a playbook can call during a conversation. The call takes no paging parameters, so one request yields the whole set.
# Update tool
Source: https://www.voiceflow.com/docs/api-reference/tool/update-tool
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/tool/{toolID}
Changes an existing tool in place. The response carries only a confirmation message, so refetch the tool to read its new values.
# Traces
Source: https://www.voiceflow.com/docs/api-reference/trace-types
Reference for every trace type returned by the Conversations API.
Traces are the output of a Voiceflow agent. Each time your application sends an action to the [Conversations API](/docs/api-reference/sections/running-agents), the runtime returns an array of trace objects describing how the agent responded. A single turn often produces multiple traces in sequence - for example, a message followed by a set of buttons.
Every trace has a `type` field that identifies what it contains, a `payload` with the relevant data, and a `time` value recording when that trace was generated as a Unix timestamp. The `time` field can be useful for debugging: steps like message generation may take noticeably longer than simple text steps, and the timestamps make that visible.
## Trace types
### text
Returned by the [Message step](/docs/documentation/build/steps/message), [Playbooks](/docs/documentation/build/steps/playbook), and no-match and no-reply reprompts.
```json
{
"type": "text",
"time": 1720552033,
"payload": {
"slate": {
"id": "unique-id",
"content": [
{
"children": [{ "text": "Hello there!" }]
},
{
"children": [{ "text": "Select an option or ask me a question" }]
}
],
"messageDelayMilliseconds": 1000
},
"message": "Hello there!\n\nSelect an option or ask me a question",
"delay": 1000
}
}
```
The `message` field contains the plain text content. The `slate` field contains the same content in a structured rich-text format. `delay` controls the pause in milliseconds before the next trace is rendered, defaulting to 1000ms.
### cardV2
Returned by the [Card step](/docs/documentation/build/steps/card). When a card contains buttons, each button's `request.type` is a Voiceflow-generated path ID. Pass that value as the `action.type` in your next request to advance the conversation along the corresponding path.
```json
{
"type": "cardV2",
"time": 1720552033,
"payload": {
"title": "This is a Card title",
"description": {
"text": "This is a Card description",
"slate": [
{
"children": [{ "text": "This is a Card description" }]
}
]
},
"imageUrl": "https://assets-global.website-files.com/example-file.png",
"buttons": [
{
"name": "Click for next step",
"request": {
"type": "path-generated-by-voiceflow",
"payload": {
"actions": [],
"label": "Click for next step"
}
}
}
]
}
}
```
### carousel
Returned by the [Carousel step](/docs/documentation/build/steps/card). The same button handling applies as with `cardV2` - pass the button's `request.type` as the `action.type` in your next request.
```json
{
"type": "carousel",
"time": 1720552033,
"payload": {
"layout": "Carousel",
"cards": [
{
"id": "unique-id",
"title": "This is a Carousel card title",
"description": {
"text": "This is a Carousel card description",
"slate": [
{
"children": [{ "text": "This is a Carousel card description" }]
}
]
},
"imageUrl": "https://assets-global.website-files.com/example-file.png",
"buttons": [
{
"name": "Click for next step",
"request": {
"type": "path-generated-by-voiceflow",
"payload": {
"label": "Click for next step",
"actions": []
}
}
}
]
}
]
}
}
```
### choice
Returned by the [Condition step](/docs/documentation/build/steps/condition) and [Playbooks](/docs/documentation/build/playbooks) or the Agent when the [buttons system tool](/docs/documentation/build/tools/system-tools) is enabled. How you handle a choice trace depends on what's in each button's `request.type`.
#### Path buttons
When buttons are connected to specific paths in your workflow, `request.type` is a Voiceflow-generated path ID. Pass it directly as `action.type` in your next request. The `label` field is optional - if included, its value is set as the `last_utterance` variable.
```json
{
"type": "choice",
"time": 1753108390491,
"payload": {
"buttons": [
{
"name": "Order coffee",
"request": {
"type": "path-cmd906pp400433b7ujbsbiotm",
"payload": {
"label": "Order coffee"
}
}
}
]
}
}
```
To handle this button click, send:
```json
{
"action": {
"type": "path-cmd906pp400433b7ujbsbiotm",
"payload": {
"label": "Order coffee"
}
}
}
```
#### Agent-generated buttons
When the [buttons system tool](/docs/documentation/build/tools/system-tools) is enabled on Playbook or on the Agent, the agent may dynamically generate buttons. These use `request.type: "text"` and simulate raw user input rather than triggering a specific path:
```json
{
"type": "choice",
"time": 1753110520157,
"payload": {
"buttons": [
{
"name": "Check account balance",
"request": {
"type": "text",
"payload": "Check account balance"
}
}
]
}
}
```
### no-reply
Returned when a No Reply timeout is active. The `timeout` value is in seconds.
```json
{
"type": "no-reply",
"time": 1720552033,
"payload": {
"timeout": 10
}
}
```
If the user doesn't respond within the timeout window, send a `no-reply` action to retrieve the configured reprompt:
```json
{
"action": {
"type": "no-reply"
}
}
```
{/* gen:start id=traces/spec sha=342b0736e5f8 */}
## Additional trace types
Every remaining `type` value in the runtime schema. Field tables are projected from the spec. Some payloads have several shapes, distinguished by a field such as `state`; where they do, the table says under which condition each field appears, and marks a field required only when every shape requires it.
### `audio`
An audio response event. The payload's `state` field selects the shape: `start` announces a `messageID`, `content` carries the audio in `content` with its `encoding`, and `end` carries the state alone.
| Field | Type | Required | Present when |
| --- | --- | --- | --- |
| `content` | string | no | `state` is `content` |
| `delay` | number | no | `state` is `start` |
| `duration` | number | no | `state` is `content` |
| `encoding` | `"audio/mp3"` or `"audio/x-mulaw"` or `"audio/pcm"` | no | `state` is `content` |
| `messageID` | string | no | `state` is `start` |
| `state` | `"start"` or `"content"` or `"end"` | yes | always |
### `block`
Marks the conversation entering a block, identified by its block ID.
| Field | Type | Required |
| --- | --- | --- |
| `blockID` | string | yes |
### `call-forward`
Signals that the call is being forwarded. The payload always carries the destination in `address` and its kind in `addressType`; a `phone` forward may also carry an `extension` and a `callerIDPassthrough` flag. See the call forward step for configuration.
| Field | Type | Required | Present when |
| --- | --- | --- | --- |
| `address` | string | yes | always |
| `addressType` | `"phone"` or `"sip"` | yes | always |
| `callerIDPassthrough` | boolean | no | `addressType` is `phone` |
| `extension` | string | no | `addressType` is `phone` |
### `channel-action`
A channel-specific action, named by the channel integration, with an action-defined payload.
| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `payload` | object | yes |
### `completion`
Marks a model completion event during the turn. Streaming clients receive the completion lifecycle described under completion event traces.
| Field | Type | Required | Present when |
| --- | --- | --- | --- |
| `ai` | boolean | no | `state` is `start` |
| `content` | string | no | `state` is `content` |
| `delay` | number | no | `state` is `start` |
| `messageID` | string | no | `state` is `start` |
| `ref` | DebugTraceRef | no | `state` is `start` or `end` |
| `sourceUrls` | object[] | no | `state` is `start` |
| `state` | `"start"` or `"content"` or `"end"` | yes | always |
### `debug`
Debug output for the turn, with a message and optional level, context, and metadata. Surfaced in agent logs rather than to end users.
| Field | Type | Required |
| --- | --- | --- |
| `context` | string | no |
| `level` | `"fatal"` or `"error"` or `"warn"` or `"info"` or `"debug"` | no |
| `message` | string | yes |
| `metadata` | object | no |
| `ref` | DebugTraceRef | no |
| `type` | string | no |
### `dtmf`
Configures keypad (DTMF) input collection on a call: whether it is enabled, the timeout, the ending delimiter, and the digit cap.
| Field | Type | Required |
| --- | --- | --- |
| `delimiter` | `"#"` or `"*"`[] | yes |
| `enabled` | boolean | yes |
| `maxDigits` | number | yes |
| `timeoutInSeconds` | number | yes |
### `entity-filling`
Requests a value for a named entity, wrapping the intent request being filled.
| Field | Type | Required |
| --- | --- | --- |
| `entityToFill` | string | yes |
| `intent` | IntentRequest | yes |
### `flow`
Marks the conversation entering a flow, identified by its diagram ID.
| Field | Type | Required |
| --- | --- | --- |
| `diagramID` | string | yes |
| `name` | string | no |
### `goto`
Instructs the client to re-send the wrapped request on the next turn.
| Field | Type | Required |
| --- | --- | --- |
| `request` | BaseRequest | yes |
### `knowledgeBase`
Reports a knowledge base retrieval: the chunks returned and the query that produced them.
| Field | Type | Required |
| --- | --- | --- |
| `chunks` | object[] | yes |
| `query` | object | no |
### `live-agent-handoff`
Signals a handoff of the conversation to a live agent platform. Every shape of the payload carries `conversationID`, `message`, and `event`; the remaining fields vary by shape, and some carry a `provider` naming the platform.
This payload has 4 shapes; a field is listed once, and marked required only when every shape both has and requires it.
| Field | Type | Required | Present when |
| --- | --- | --- | --- |
| `agent` | object | no | always |
| `config` | LiveAgentHandoffWidgetConfig | no | some shapes (1 of 4) |
| `continueMessage` | string | no | some shapes (1 of 4) |
| `conversationID` | string | yes | always |
| `downloadMessage` | string | no | some shapes (1 of 4) |
| `event` | `"chat_started"` | yes | always |
| `file` | object | no | some shapes (1 of 4) |
| `message` | string | yes | always |
| `newConversationMessage` | string | no | some shapes (1 of 4) |
| `provider` | `"ujet"` or `"genesys"` or `"kustomer"` or `"dixa"` | no | some shapes (1 of 4) |
| `translationKey` | string | no | always |
| `translationParams` | object | no | always |
### `log`
Diagnostic log output attached to the turn. The `payload` is always present and is a free-form object: the spec declares no named fields on it and permits any.
### `path`
Reports which path the conversation took out of a step.
| Field | Type | Required |
| --- | --- | --- |
| `path` | string | yes |
### `realtime-agent`
Marks realtime agent activity on the turn. The payload's `action` field selects the shape: `START` carries `input` and `output`, while `END` and `INTERRUPTED` carry the action alone.
| Field | Type | Required | Present when |
| --- | --- | --- | --- |
| `action` | `"START"` or `"END"` or `"INTERRUPTED"` | yes | always |
| `input` | object | no | `action` is `START` |
| `output` | object | no | `action` is `START` |
### `reasoning`
Marks model reasoning activity during the turn. The payload's `state` field selects the shape: `content` carries a `content` string, `final` carries a `message`, and `start` and `end` carry the state alone.
| Field | Type | Required | Present when |
| --- | --- | --- | --- |
| `content` | string | no | `state` is `content` |
| `message` | string | no | `state` is `final` |
| `state` | `"start"` or `"content"` or `"end"` or `"final"` | yes | always |
### `speak`
A spoken response for voice channels, carrying the message text and optionally a synthesized audio source and voice name.
| Field | Type | Required |
| --- | --- | --- |
| `ai` | boolean | no |
| `isPrompt` | boolean | no |
| `message` | string | yes |
| `src` | string | no |
| `type` | `"audio"` or `"message"` | yes |
| `voice` | string | no |
### `stream`
An audio stream event. The payload carries the source in `src`, a `token`, and an `action` of `LOOP`, `PLAY`, `PAUSE`, or `END`; `title`, `description`, `iconImage`, `backgroundImage`, and `loop` are optional.
| Field | Type | Required |
| --- | --- | --- |
| `action` | `"LOOP"` or `"PLAY"` or `"PAUSE"` or `"END"` | yes |
| `backgroundImage` | string | no |
| `description` | string | no |
| `iconImage` | string | no |
| `loop` | boolean | no |
| `src` | string | yes |
| `title` | string | no |
| `token` | string | yes |
### `tool-call`
Marks a tool call made by the agent during the turn. The payload always carries the `callID` and a `state` of `start` or `end`; a `start` may also carry a `sound`.
| Field | Type | Required | Present when |
| --- | --- | --- | --- |
| `callID` | string | yes | always |
| `sound` | object | no | `state` is `start` |
| `state` | `"start"` or `"end"` | yes | always |
### `visual`
Displays an image, with optional device sizing and layout options.
| Field | Type | Required |
| --- | --- | --- |
| `canvasVisibility` | `"full"` or `"hidden"` or `"cropped"` | no |
| `device` | string | no |
| `dimensions` | object | no |
| `frameType` | string | no |
| `image` | string | yes |
| `options` | object | no |
| `visualType` | `"image"` | no |
{/* gen:end id=traces/spec */}
### Custom actions
Custom action traces can be returned by functions and use the string you defined in Voiceflow as the `type` value. The `defaultPath` field indicates which path is set as the default: `0` for the first path, `1` for the second, and so on. Their payload is provided as JSON, as shown:
```json
{
"type": "calendar",
"time": 1720552033,
"payload": {
"today": 1700096585398
},
"defaultPath": 0,
"paths": [
{ "event": { "type": "done" } },
{ "event": { "type": "cancel" } }
]
}
```
### end
Returned when the conversation reaches an End step. On receiving this trace, your application should treat the session as closed.
```json
{
"type": "end",
"time": 1720552033,
"payload": null
}
```
## Completion event traces
When using the streaming endpoint, you may also encounter `completion` traces. A single `completion` type marks the lifecycle of an AI generation event within a stream: the payload's `state` field moves through `start`, `content`, and `end`. See [Completion events](/docs/api-reference/conversations-api/completion-events) for the full stream format.
# Create property
Source: https://www.voiceflow.com/docs/api-reference/transcript-property/create-property
/specs-prettified/realtime/openapi.stable.json post /v1/stable/transcript-property
Adds a transcript property to the project, a label you define once and then set on individual conversations. The response carries the ID that later calls address it by.
# Delete property
Source: https://www.voiceflow.com/docs/api-reference/transcript-property/delete-property
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/transcript-property/{propertyID}
Deletes a single transcript property by ID. A transcript property is a label you define once and then set on individual conversations. The response carries only a confirmation message, so refetch the transcript properties to see what is left.
# Get property
Source: https://www.voiceflow.com/docs/api-reference/transcript-property/get-property
/specs-prettified/realtime/openapi.stable.json get /v1/stable/transcript-property/{propertyID}
Returns a single transcript property by ID, with the fields that define it. A transcript property is a label you define once and then set on individual conversations.
# List properties
Source: https://www.voiceflow.com/docs/api-reference/transcript-property/list-properties
/specs-prettified/realtime/openapi.stable.json get /v1/stable/transcript-property
Returns every transcript property in the project. A transcript property is a label you define once and then set on individual conversations. The call takes no paging parameters, so one request yields the whole set.
# Set property value
Source: https://www.voiceflow.com/docs/api-reference/transcript-property/set-property-value
/specs-prettified/realtime/openapi.stable.json put /v1/stable/transcript-property/{propertyID}/value
Sets a property’s value on one conversation. Defining the property and setting it are separate calls, so the definition is reused across every transcript that carries it.
# Update property
Source: https://www.voiceflow.com/docs/api-reference/transcript-property/update-property
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/transcript-property/{propertyID}
Changes an existing transcript property in place. The response carries only a confirmation message, so refetch the transcript property to read its new values.
# Get transcript
Source: https://www.voiceflow.com/docs/api-reference/transcript/get-transcript
/specs-prettified/realtime/openapi.stable.json get /v1/stable/transcript/{transcriptID}
Returns one recorded conversation, including the turns exchanged and the traces behind them. Set `filterConversation` to keep only `text`, `speak`, and `live-agent-handoff` traces, plus any types listed in `customTraceTypes`.
# Search transcripts
Source: https://www.voiceflow.com/docs/api-reference/transcript/search-transcripts
/specs-prettified/realtime/openapi.stable.json post /v1/stable/transcript/search
Finds recorded conversations matching a filter. Unlike the list calls elsewhere in this API, the body takes `take` and `skip`, so results arrive a page at a time.
# Create many variables
Source: https://www.voiceflow.com/docs/api-reference/variable/create-many-variables
/specs-prettified/realtime/openapi.stable.json post /v1/stable/variable/batch
Adds several variables to the project in one request, each taking the fields the single-create call takes. The response carries the created variables in the same shape the list call returns.
# Create variable
Source: https://www.voiceflow.com/docs/api-reference/variable/create-variable
/specs-prettified/realtime/openapi.stable.json post /v1/stable/variable
Adds a variable to the project, a named slot of project state an agent can read and write. The response carries the ID that later calls address it by.
# Delete variable
Source: https://www.voiceflow.com/docs/api-reference/variable/delete-variable
/specs-prettified/realtime/openapi.stable.json 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.
# Get variable
Source: https://www.voiceflow.com/docs/api-reference/variable/get-variable
/specs-prettified/realtime/openapi.stable.json get /v1/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.
# List variables
Source: https://www.voiceflow.com/docs/api-reference/variable/list-variables
/specs-prettified/realtime/openapi.stable.json get /v1/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.
# Update variable
Source: https://www.voiceflow.com/docs/api-reference/variable/update-variable
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/variable/{variableID}
Changes an existing variable in place. The response carries only a confirmation message, so refetch the variable to read its new values.
# Organization events webhooks
Source: https://www.voiceflow.com/docs/api-reference/webhooks/org-events
Receive organization level events to your webhooks.
If you're using Voiceflow within a larger organization, you might want to integrate with your existing observability or testing tools. Organization events webhooks let you automatically receive updates whenever something happens in your organization - for example, when a new project is created. Just provide a webhook URL, and Voiceflow will send event data there in real time.
## Configuring your webhook settings
If you're less technical, we recommend using a tool like Make to generate a webhook URL and run automations. If you're a developer, you can hook into your existing infrastructure using any tool that can receive and process JSON payloads.
To enable sending data to a webhook whenever key events happen within an organization, head to your [Voiceflow dashboard](https://creator.voiceflow.com), click the **Settings** button in the bottom left corner, then select **Organization**. You can then add the URL that you'd like to send events to in the box provided.
Once you've set a webhook URL, all future events will be automatically sent to it.
## Supported events
The following organization-level events will be sent to the provided URL:
| Human-readable name | Name |
| -------------------------------- | ----------------------------------------------------------------------------------------------------- |
| New project created | [`organization.project.created`](#organization-project-created) |
| Project deleted | [`organization.project.deleted`](#organization-project-deleted) |
| Project environment created | [`organization.project.environment.created`](#organization-project-environment-created) |
| Project environment published | [`organization.project.environment.published`](#organization-project-environment-published) |
| Project environment merged | [`organization.project.environment.merged`](#organization-project-environment-merged) |
| Project environment deleted | [`organization.project.environment.deleted`](#organization-project-environment-deleted) |
### `organization.project.created`
Sent when a new project is created in the organization.
```typescript
{
"type": "organization.project.created",
"data": {
"createdBy": {
"type": string, // e.g. "user"
"userEmail": string
},
"organizationID": string,
"projectID": string,
"projectMetadata": {
"name": string
},
"workspaceID": string
},
"resource": string, // organization-{organizationID}
"time": number // unix timestamp MS, event time
}
```
```json
{
"data": {
"createdBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"organizationID": "LVkmPy8AE2",
"projectID": "6a16f4549e4196323d8a49b9",
"projectMetadata": {
"name": "My new project"
},
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889237608,
"type": "organization.project.created"
}
```
### `organization.project.deleted`
Sent when a project is deleted from the organization.
```typescript
{
"type": "organization.project.deleted",
"data": {
"deletedBy": {
"type": string, // e.g. "user"
"userEmail": string
},
"organizationID": string,
"projectID": string,
"projectMetadata": {
"name": string
},
"workspaceID": string
},
"resource": string, // organization-{organizationID}
"time": number // unix timestamp MS, event time
}
```
```json
{
"data": {
"deletedBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"organizationID": "LVkmPy8AE2",
"projectID": "6a16f4789e4196323d8a49c3",
"projectMetadata": {
"name": "Legacy support agent"
},
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889287387,
"type": "organization.project.deleted"
}
```
### `organization.project.environment.created`
Sent when a new environment is created within a project. The `source` describes the environment the new one was branched from.
```typescript
{
"type": "organization.project.environment.created",
"data": {
"createdBy": {
"type": string, // e.g. "user"
"userEmail": string
},
"createdProjectEnvironmentID": string,
"createdProjectEnvironmentMetadata": {
"alias": string,
"isLive": boolean,
"name": string,
"trafficPercentage": number
},
"organizationID": string,
"projectID": string,
"projectMetadata": {
"name": string
},
"source": {
"environmentID": string,
"environmentMetadata": {
"alias": string,
"isLive": boolean,
"name": string,
"trafficPercentage": number
},
"type": string // e.g. "environment"
},
"workspaceID": string
},
"resource": string, // organization-{organizationID}
"time": number // unix timestamp MS, event time
}
```
```json
{
"data": {
"createdBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"createdProjectEnvironmentID": "6a16f4dc9e4196323d8a49e5",
"createdProjectEnvironmentMetadata": {
"alias": "optimizeglobalprompt",
"isLive": false,
"name": "Optimize global prompt",
"trafficPercentage": 0
},
"organizationID": "LVkmPy8AE2",
"projectID": "69e8b60a99c9a35e1a5e8872",
"projectMetadata": {
"name": "My support agent"
},
"source": {
"environmentID": "69e8b60a99c9a35e1a5e8875",
"environmentMetadata": {
"alias": "main",
"isLive": true,
"name": "Main",
"trafficPercentage": 70
},
"type": "environment"
},
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889372749,
"type": "organization.project.environment.created"
}
```
### `organization.project.environment.published`
Sent when an environment within a project is published. `publishedVersionIDBefore` and `publishedVersionIDAfter` let you track what changed.
```typescript
{
"type": "organization.project.environment.published",
"data": {
"organizationID": string,
"projectID": string,
"projectMetadata": {
"name": string
},
"publishedBy": {
"type": string, // e.g. "user"
"userEmail": string
},
"publishedProjectEnvironmentID": string,
"publishedProjectEnvironmentMetadata": {
"alias": string,
"isLive": boolean,
"name": string,
"trafficPercentage": number
},
"publishedVersionIDAfter": string,
"publishedVersionIDBefore": string,
"workspaceID": string
},
"resource": string, // organization-{organizationID}
"time": number // unix timestamp MS, event time
}
```
```json
{
"data": {
"organizationID": "LVkmPy8AE2",
"projectID": "69e8b60a99c9a35e1a5e8872",
"projectMetadata": {
"name": "My support agent"
},
"publishedBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"publishedProjectEnvironmentID": "69e8b60a99c9a35e1a5e8875",
"publishedProjectEnvironmentMetadata": {
"alias": "main",
"isLive": true,
"name": "Main",
"trafficPercentage": 70
},
"publishedVersionIDAfter": "6a16f4b29e4196323d8a49db",
"publishedVersionIDBefore": "69e8e543ce546b913fc2c965",
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889330124,
"type": "organization.project.environment.published"
}
```
```json
{
"data": {
"organizationID": "LVkmPy8AE2",
"projectID": "69e8b60a99c9a35e1a5e8872",
"projectMetadata": {
"name": "My support agent"
},
"publishedBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"publishedProjectEnvironmentID": "6a16f4dc9e4196323d8a49e5",
"publishedProjectEnvironmentMetadata": {
"alias": "optimizeglobalprompt",
"isLive": false,
"name": "Optimize global prompt",
"trafficPercentage": 0
},
"publishedVersionIDAfter": "6a16f5129e4196323d8a49f1",
"publishedVersionIDBefore": "6a16f4dc9e4196323d8a49e3",
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889426435,
"type": "organization.project.environment.published"
}
```
### `organization.project.environment.merged`
Sent when one environment is merged into another. `sourceProjectEnvironmentRemoved` indicates whether the source environment was deleted as part of the merge.
```typescript
{
"type": "organization.project.environment.merged",
"data": {
"mergedBy": {
"type": string, // e.g. "user"
"userEmail": string
},
"organizationID": string,
"projectID": string,
"projectMetadata": {
"name": string
},
"sourceProjectEnvironmentID": string,
"sourceProjectEnvironmentMetadata": {
"alias": string,
"isLive": boolean,
"name": string,
"trafficPercentage": number
},
"sourceProjectEnvironmentRemoved": boolean,
"targetProjectEnvironmentID": string,
"targetProjectEnvironmentMetadata": {
"alias": string,
"isLive": boolean,
"name": string,
"trafficPercentage": number
},
"workspaceID": string
},
"resource": string, // organization-{organizationID}
"time": number // unix timestamp MS, event time
}
```
```json
{
"data": {
"mergedBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"organizationID": "LVkmPy8AE2",
"projectID": "69e8b60a99c9a35e1a5e8872",
"projectMetadata": {
"name": "My support agent"
},
"sourceProjectEnvironmentID": "6a16f4dc9e4196323d8a49e5",
"sourceProjectEnvironmentMetadata": {
"alias": "optimizeglobalprompt",
"isLive": false,
"name": "Optimize global prompt",
"trafficPercentage": 0
},
"sourceProjectEnvironmentRemoved": true,
"targetProjectEnvironmentID": "69e8b60a99c9a35e1a5e8875",
"targetProjectEnvironmentMetadata": {
"alias": "main",
"isLive": true,
"name": "Main",
"trafficPercentage": 70
},
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889488361,
"type": "organization.project.environment.merged"
}
```
### `organization.project.environment.deleted`
Sent when an environment is deleted from a project.
```typescript
{
"type": "organization.project.environment.deleted",
"data": {
"deletedBy": {
"type": string, // e.g. "user"
"userEmail": string
},
"deletedProjectEnvironmentID": string,
"deletedProjectEnvironmentMetadata": {
"alias": string,
"isLive": boolean,
"name": string,
"trafficPercentage": number
},
"organizationID": string,
"projectID": string,
"projectMetadata": {
"name": string
},
"workspaceID": string
},
"resource": string, // organization-{organizationID}
"time": number // unix timestamp MS, event time
}
```
```json
{
"data": {
"deletedBy": {
"type": "user",
"userEmail": "user@voiceflow.com"
},
"deletedProjectEnvironmentID": "69e8b64d99c9a35e1a5e888b",
"deletedProjectEnvironmentMetadata": {
"alias": "feature-upselling",
"isLive": false,
"name": "Old unused environment",
"trafficPercentage": 0
},
"organizationID": "LVkmPy8AE2",
"projectID": "69e8b60a99c9a35e1a5e8872",
"projectMetadata": {
"name": "My support agent"
},
"workspaceID": "95kwAZ63nO"
},
"resource": "organization-LVkmPy8AE2",
"time": 1779889527687,
"type": "organization.project.environment.deleted"
}
```
## Verifying requests come from Voiceflow
Once you enter a webhook URL into the settings page, you'll automatically be provided with a webhook secret. This can be used to verify that events received by the webhook were really sent by Voiceflow. [Follow these instructions to learn how to verify events using the webhook secret](https://docs.svix.com/receiving/verifying-payloads/how-manual).
If you accidentally leak your webhook secret, you can regenerate it using the 🔄 button on the settings page. Note that your previous webhook secret will remain valid for 24 hours after you regenerate it.
If you're receiving data from behind a restrictive firewall, you should know that events will come from one of [Svix's IP addresses](https://docs.svix.com/receiving/source-ips), rather than Voiceflow's.
# Session lifecycle webhook
Source: https://www.voiceflow.com/docs/api-reference/webhooks/session-lifecycle
Subscribe to session and call lifecycle webhook events so external systems get notified when Voiceflow conversations start and end.
The session lifecycle webhook notifies your systems in real time whenever a conversation starts or ends, letting you run automations around each conversation without polling for changes.
A common use is running automations once a conversation ends, without adding latency to the conversation itself. For example, you can sync conversation data to your CRM, kick off a downstream workflow in your own systems, or notify another service that a conversation has wrapped up. Because this work runs on your side in response to the webhook, none of it slows down the live conversation.
Add your webhook URL to your project under **Settings → Webhooks**.
A new webhook listens for every event. To narrow that down, choose **Listen for specific events** and tick only the ones you want: each is listed with its event name, grouped into [session events](#session-events) and [call events](#call-events). You can change the selection at any time, and deprecated events are labelled as such in the list.
## Events
Voiceflow will send POST requests to your webhook URL on the following events.
| Human-readable name | Name | Category |
| --- | --- | --- |
| Session started | [`runtime.session.start`](#runtime-session-start) | [Session events](#session-events) |
| Session ended | [`runtime.session.end`](#runtime-session-end) | [Session events](#session-events) |
| Call started | [`runtime.call.start`](#runtime-call-start) | [Call events](#call-events) |
| Call ended | [`runtime.call.end`](#runtime-call-end) | [Call events](#call-events) |
Three older `.v2` variants are deprecated and stop firing on **October 9, 2026**. See [Deprecated events](#deprecated-events).
## Session events
Session events fire whenever a conversation starts or ends, across every project and every channel. A session is the conversation itself, the state your agent builds up as it goes, so every conversation has one. These are the events most integrations listen for.
A session has to exist for these events to fire. The chat widget, voice conversations, and the Start session endpoint each create one; the deprecated legacy Interact endpoints don't, so conversations run through those produce no session events.
### `runtime.session.start`
This event is sent when a new session is started for a user.
```typescript
{
"type": "runtime.session.start",
"data": {
"userID": string,
"projectID": string,
"environmentID": string,
"sessionID": string,
"startTime": number, // unix timestamp MS
// the fields below may be null or absent — see "Optional fields"
"versionID"?: string | null, // same value as environmentID
"transcriptID"?: string | null,
"versionVariant"?: "draft" | "published" | null,
"projectEnvironmentID"?: string | null,
"projectEnvironmentAlias"?: string | null
}
"time": number // unix timestamp MS, event time
"resource": string // project-{projectID}
}
```
```json
{
"type": "runtime.session.start",
"data": {
"environmentID": "6a15b5f6a85b1b570a8773cf",
"projectID": "69f9fa36eeb8f50e7cfd2d5f",
"sessionID": "6a15b6093f95e60007ec4e04",
"startTime": 1779807753396,
"userID": "g4dq75wr6asov6z571860xg0",
"versionID": "6a15b5f6a85b1b570a8773cf",
"transcriptID": "6a15b6093f95e60007ec4e04",
"versionVariant": "published",
"projectEnvironmentID": "6a15b5f6a85b1b570a8773d4",
"projectEnvironmentAlias": "production"
},
"resource": "project-69f9fa36eeb8f50e7cfd2d5f",
"time": 1779807753433
}
```
### `runtime.session.end`
This event is sent when a session ends: because the conversation reached an end, because the caller hung up, or because the session sat idle past its timeout.
This event doesn't necessarily arrive when the user stops talking to your agent. Closing a chat widget sends no end signal, so unless your agent explicitly ends the conversation, the session runs to its idle timeout and the event arrives then, potentially long after the user left. To react the moment a conversation stops, drive it from your agent's own end-of-conversation logic.
```typescript
{
"type": "runtime.session.end",
"data": {
"userID": string,
"projectID": string,
"environmentID": string,
"sessionID": string,
"startTime": number, // unix timestamp MS
"endTime": number, // unix timestamp MS
// the fields below may be null or absent — see "Optional fields"
"endReason"?: string | null, // why the session ended, arbitrary string
"versionID"?: string | null, // same value as environmentID
"transcriptID"?: string | null,
"versionVariant"?: "draft" | "published" | null,
"projectEnvironmentID"?: string | null,
"projectEnvironmentAlias"?: string | null
}
"time": number // unix timestamp MS, event time
"resource": string // project-{projectID}
}
```
```json
{
"type": "runtime.session.end",
"data": {
"endTime": 1779807762998,
"environmentID": "6a15b5f6a85b1b570a8773cf",
"projectID": "69f9fa36eeb8f50e7cfd2d5f",
"sessionID": "6a15b6093f95e60007ec4e04",
"startTime": 1779807753396,
"userID": "g4dq75wr6asov6z571860xg0",
"endReason": "Session ended due to inactivity timeout",
"versionID": "6a15b5f6a85b1b570a8773cf",
"transcriptID": "6a15b6093f95e60007ec4e04",
"versionVariant": "published",
"projectEnvironmentID": "6a15b5f6a85b1b570a8773d4",
"projectEnvironmentAlias": "production"
},
"resource": "project-69f9fa36eeb8f50e7cfd2d5f",
"time": 1779807763081
}
```
## Call events
Call events fire on voice conversations only. They carry call-level details that exist only on a call, such as the phone numbers involved and why the call ended.
A voice conversation emits call events **and** session events, because the two describe different things: the call is the voice connection, and the session is the conversation carried over it. Check `type` to tell which event you're handling, and use `data.sessionID` to join the two.
Their end events are not interchangeable either:
- `runtime.call.end` fires when the voice connection is torn down.
- `runtime.session.end` fires when the session expires. On a normal hangup that follows within a few seconds, because hanging up marks the session as expired. If the hangup never reaches Voiceflow, the session ends on its idle timeout instead, which can be much later.
Use `runtime.call.end` for call duration and `runtime.session.end` for conversation lifetime.
Calls and sessions aren't one-to-one. A caller who reaches your agent again while their previous session is still active reuses that session, so the second call emits `runtime.call.start` and `runtime.call.end` with no new `runtime.session.start`. That session's `runtime.session.end` arrives once the session itself expires, after the last call. On a reused session, `data.sessionID` and `data.transcriptID` are `null` on `runtime.call.start`, so that event can't be joined to its session.
### `runtime.call.start`
This event is sent when a voice call starts: an inbound or outbound phone call, or a voice call from the web widget, including test calls in the Voiceflow editor.
```typescript
{
"type": "runtime.call.start",
"data": {
"userID": string,
"projectID": string,
"environmentID": string,
"startTime": number, // unix timestamp MS
"platform": "twilio" | "telnyx" | "vonage" | "voiceflow" | "web-voice",
"metadata": object, // depends on "platform"
// the fields below may be null or absent — see "Optional fields"
"sessionID"?: string | null, // the session this call is attached to
"versionID"?: string | null, // same value as environmentID
"transcriptID"?: string | null,
"versionVariant"?: "draft" | "published" | null,
"projectEnvironmentID"?: string | null,
"projectEnvironmentAlias"?: string | null
}
"time": number // unix timestamp MS, event time
"resource": string // project-{projectID}
}
```
```json
{
"type": "runtime.call.start",
"data": {
"userID": "+19876543210",
"environmentID": "69f3df348d8088f34a622739",
"projectID": "6772da2e485189279fa5b9da",
"startTime": 1743563467788,
"platform": "twilio",
"metadata": {
"callSid": "CA01ed76f14fee29c50f5de59400474006",
"callType": "inbound",
"userNumber": "+19876543210",
"agentNumber": "+17782006110"
},
"sessionID": "69f3df3a3f95e60007ec4e04",
"versionID": "69f3df348d8088f34a622739",
"transcriptID": "69f3df3a3f95e60007ec4e04",
"versionVariant": "published",
"projectEnvironmentID": "69f3df348d8088f34a62273f",
"projectEnvironmentAlias": "production"
},
"time": 1743563467874,
"resource": "project-6772da2e485189279fa5b9da"
}
```
### `runtime.call.end`
This event is sent when a call is completed.
```typescript
{
"type": "runtime.call.end",
"data": {
"userID": string,
"projectID": string,
"environmentID": string,
"startTime": number, // unix timestamp MS
"endTime": number, // unix timestamp MS
"endReason": string, // why the call ended, arbitrary string, common reasons include "hangup" "end trace" "twiml" "answering machine"
"platform": "twilio" | "telnyx" | "vonage" | "voiceflow" | "web-voice",
"metadata": object, // depends on "platform"
// the fields below may be null or absent — see "Optional fields"
"sessionID"?: string | null, // the session this call was attached to
"versionID"?: string | null, // same value as environmentID
"transcriptID"?: string | null,
"versionVariant"?: "draft" | "published" | null,
"projectEnvironmentID"?: string | null,
"projectEnvironmentAlias"?: string | null
}
"time": number // unix timestamp MS
"resource": string // project-{projectID}
}
```
```json
{
"type": "runtime.call.end",
"data": {
"userID": "+19876543210",
"environmentID": "69f3df348d8088f34a622739",
"projectID": "6772da2e485189279fa5b9da",
"startTime": 1743563467788,
"endTime": 1743563467834,
"endReason": "hangup",
"platform": "twilio",
"metadata": {
"callSid": "CA01ed76f14fee29c50f5de59400474006",
"callType": "inbound",
"userNumber": "+19876543210",
"agentNumber": "+17782006110"
},
"sessionID": "69f3df3a3f95e60007ec4e04",
"versionID": "69f3df348d8088f34a622739",
"transcriptID": "69f3df3a3f95e60007ec4e04",
"versionVariant": "published",
"projectEnvironmentID": "69f3df348d8088f34a62273f",
"projectEnvironmentAlias": "production"
},
"time": 1743563467874,
"resource": "project-6772da2e485189279fa5b9da"
}
```
## Optional fields
Several fields on the four events above are **optional and nullable**: `versionID`, `transcriptID`, `versionVariant`, `projectEnvironmentID`, `projectEnvironmentAlias`, `sessionID` (call events only), and `endReason` (on `runtime.session.end`).
They are populated whenever the value is available, and are `null` otherwise. Treat a missing or `null` value as "not known for this conversation" rather than as an error, and don't require them to be present when parsing a payload.
`endReason` on `runtime.session.end` is typed as nullable but in practice always carries a value. Sessions that simply time out report `"Session ended due to inactivity timeout"`, and a session displaced by a new one reports `"Session expired because a new one was started"`. It's an arbitrary string, so match on it defensively rather than treating the set as fixed.
`versionID` carries the same value as `environmentID`. It exists so that consumers written against the deprecated `.v2` events, which used the name `versionID`, keep working after migrating.
`transcriptID` carries the same value as `sessionID`, because a conversation's transcript is keyed on the session that produced it. It's `null` when transcripts are disabled for the session, which is the case to guard against if you use it to build transcript links.
## Deprecated events
`runtime.session.start.v2`, `runtime.call.start.v2` and `runtime.call.end.v2` are deprecated. They will **stop firing on October 9, 2026**. If you subscribe to any of them, switch to the corresponding event without the `.v2` suffix before then.
Until that date the deprecated events keep firing exactly as they do today, alongside their replacements, so you can migrate at your own pace. If you subscribe to both an event and its `.v2` variant during this window you'll receive both, and should ignore one of them.
| Deprecated event | Replace with |
| --- | --- |
| `runtime.session.start.v2` | [`runtime.session.start`](#runtime-session-start) |
| `runtime.call.start.v2` | [`runtime.call.start`](#runtime-call-start) |
| `runtime.call.end.v2` | [`runtime.call.end`](#runtime-call-end) |
The `.v2` events existed only to add richer metadata. That metadata now ships on the standard events, so the two payloads carry the same information. Differences to handle when you migrate:
| Field on the `.v2` event | On the replacement event |
| --- | --- |
| `versionID` | `versionID`, carrying the same value. The replacement events also include `environmentID` with that value. |
| `sessionID`, `transcriptID`, `versionVariant`, `projectEnvironmentID`, `projectEnvironmentAlias` | Same names and values, but [optional and nullable](#optional-fields). The `.v2` events only fired when these were all known; the replacements fire on every session or call, so your handler needs to tolerate `null`. |
| `endReason` (on `runtime.call.end.v2`) | `endReason` on `runtime.call.end`, always present and never `null`. |
`runtime.session.end.v2` has also been removed. Unlike the events above it never fired, because its trigger condition depended on data that was never recorded, so it has no subscribers and no migration path is needed. Use [`runtime.session.end`](#runtime-session-end), which now carries the fields `runtime.session.end.v2` was intended to add.
## Best practices
- Check `type` when evaluating a response. There may be additional types of events in the future with a different shaped request body, as well as new properties and metadata.
- **Parse payloads permissively.** New fields are added to existing events without introducing a new event name or version, so treat unrecognized properties as expected. A new event *name* is only introduced when an existing field's meaning or shape changes.
- Don't require the [optional fields](#optional-fields) to be present. Handle `null`.
- `data.metadata` is only included on call events. Check `data.platform` before reading it, as the available fields vary by platform (eg: `data.metadata.callSid` isn't present on a `"web-voice"` call).
- Join call events to session events on `data.sessionID` where it's present, and don't assume one call per session. See [Call events](#call-events).
- If you're using the same webhook URL across multiple projects, check `data.projectID` to tell them apart.
# Create workspace
Source: https://www.voiceflow.com/docs/api-reference/workspace/create-workspace
/specs-prettified/realtime/openapi.stable.json post /v1/stable/workspace
Adds a workspace to the account, the container that groups projects and the people who work on them. The response carries the ID that later calls address it by.
# Delete workspace
Source: https://www.voiceflow.com/docs/api-reference/workspace/delete-workspace
/specs-prettified/realtime/openapi.stable.json delete /v1/stable/workspace/{workspaceID}
Deletes a single workspace by ID. A workspace is the container that groups projects and the people who work on them. The response carries only a confirmation message, so refetch the workspaces to see what is left.
# Get workspace
Source: https://www.voiceflow.com/docs/api-reference/workspace/get-workspace
/specs-prettified/realtime/openapi.stable.json get /v1/stable/workspace/{workspaceID}
Returns a single workspace by ID, with the fields that define it. A workspace is the container that groups projects and the people who work on them.
# List workspaces
Source: https://www.voiceflow.com/docs/api-reference/workspace/list-workspaces
/specs-prettified/realtime/openapi.stable.json get /v1/stable/workspace
Returns every workspace in the account. A workspace is the container that groups projects and the people who work on them. The call takes no paging parameters, so one request yields the whole set.
# Update workspace
Source: https://www.voiceflow.com/docs/api-reference/workspace/update-workspace
/specs-prettified/realtime/openapi.stable.json patch /v1/stable/workspace/{workspaceID}
Changes an existing workspace in place. The response carries only a confirmation message, so refetch the workspace to read its new values.
# Changelog
Source: https://www.voiceflow.com/docs/changelog/changelog
Stay up to date with Voiceflow product updates, new features, bug fixes, and platform improvements shipped across the agent builder and APIs.
## Instruction patching
Agent instructions, global prompts, and playbook instructions can now be read, searched, and patched line by line through the API. You can edit a single line in a 20,000-line prompt without re-sending the entire document, and search instructions to locate specific lines.
Use the new patch endpoints to update individual lines by their line number or search pattern. This applies to instructions at the agent level, global prompt level, and within playbooks.
Full document replacement remains available. Line-by-line patching is an alternative for large instruction sets where targeted edits are more efficient.
{/* manifest: agent-instructions-the-global-prompt-and-playbook-instructio */}
## Atlas reads your conversations
Atlas can now answer questions about your conversations in bulk. Ask why calls dropped last Tuesday, or which conversations scored badly on an evaluation, and it searches your transcripts, reads the ones that matter, and reports back, instead of you opening them one at a time.
Point it at a date range, an environment, or an evaluation score. It can summarize a single conversation from a link, or run named evaluations across everything it found in one batch. Batches spend your workspace's evaluation quota and write scores onto the transcripts, so Atlas tells you the cost before it starts.
{/* manifest: atlas-searches-reads-and-scores-conversations-through-purpos */}
## Reasoning effort
You can now set how hard a Claude model thinks before it answers. Pick a Claude model served through Bedrock and a **Reasoning effort** slider appears, with stops for Off, Adaptive, Low, Medium and High. Leave it alone and the model keeps its own default.
Set it in **Settings** → **Behaviour** → **Model & reasoning**, or from the **Model** popover on a playbook or prompt. Thinking tokens are billed as output, so Off is a cost control as much as a speed one.
{/* manifest: reasoning-effort-including-off-and-adaptive-is-selectable-fo */}
## Phone call audio
We have improved how phone call audio is processed before the agent hears it. There were cases where noise cancellation was stripping parts of what the caller said, so the agent missed some of the utterance and it did not reach the transcript. Callers now come through in full.
Nothing to configure, and this applies to every phone call.
{/* manifest: noise-cancellation-on-phone-calls-no-longer-removes-the-call */}
## Evaluation run scope
An evaluation can now be scoped to conversations that ran on a published environment, or to draft ones, instead of scoring everything. Resolution rate and Conversion rate are published-only by default, so test traffic no longer skews them.
Set `runScope` to `published`, `draft` or `both` through the API. It applies to automatic scoring only: a batch run from the Transcripts tab still runs on exactly the transcripts you pick.
Evaluations score what already happened. Tests pin what must happen.
{/* manifest: an-evaluation-can-be-scoped-to-run-automatically-on-publishe */}
## Billing user role
Billing access is now decided by a member's workspace role alone. Owner, Admin and Billing roles keep it, as do organization admins.
Giving someone edit or admin access to a single project used to carry billing access with it. If you were relying on that, give them the workspace **Billing** role instead.
{/* manifest: workspace-billing-permissions-are-decided-by-the-workspace-r */}
## Atlas writes your tests
Atlas can now create tests in the **Tests** tab: scripted turn-by-turn conversations, persona simulations, and checks on what the agent said, where it routed and which tools it called. It can also turn a conversation into a regression test, whether that conversation worked or failed.
After a smoke conversation passes, Atlas offers to pin it as a test. Before a publish or merge to Main, it offers to run the suite first. Atlas writes the test and hands the run back to you to trigger.
{/* manifest: atlas-can-author-convert-and-read-saved-agent-tests-through- */}
## Atlas improvements
Atlas now edits prompts in front of you. Ask it to change your global prompt, agent instructions or a playbook's instructions, and you watch the rewrite happen in the editor rather than waiting for a finished result. In Safe mode the proposal appears as a word-level diff you accept or reject; in Autonomous mode the text is typed straight in.
You can also ask about one part of a prompt instead of the whole thing. Select any text in an editor and choose **Ask Atlas** from the toolbar above the selection, and that passage is attached to your next question as a chip.
And Atlas can set up credentials with you. When something needs a secret, an integration or an MCP server, it offers a card that opens the normal Voiceflow flow. You fill it in, the card reports back, and Atlas carries on from where it stopped. **The credential is entered by you and never passes through the chat or the model.**
{/* manifest: atlas-s-prompt-and-instruction-edits-stream-into-the-prompt-, ask-atlas-about-a-selected-passage-of-a-prompt-from-the-edit, atlas-sets-up-secrets-integrations-and-mcp-servers-by-offeri */}
## Secret and integration endpoints
Secrets and third-party integrations can now be listed, created, connected and disconnected through the stable API, the CLI and the Voiceflow MCP server, scoped by project. Secret values are write-only and never returned.
Integrations report whether they can be connected through the API at all. Browser-flow ones such as Zendesk and Salesforce still have to be connected in the builder. A credential value is refused when it arrives from an MCP client.
{/* manifest: secret-and-integration-resource-families-on-the-stable-api-w */}
## Pending changes indicator
An environment with unpublished work now says so. The **Publish** control carries an amber dot, and its menu offers **View pending changes** so you can read the diff without opening the Publish form. The environments table shows the same dot in place of the old Draft tag.
{/* manifest: an-environment-with-unpublished-work-is-marked-on-the-publis */}
## Safe mode in Atlas
Safe mode is how Atlas works by default: it pauses and asks before anything that changes your project, and runs read-only work such as listing, fetching, exporting, querying analytics and searching transcripts without interrupting you.
It now decides what counts as a change per operation, rather than inferring it from the operation's name. Anything implemented as a write asks first even if it reads like a lookup, and any newly added operation asks until it is classified. Switch between Safe and Autonomous from the pill in the Atlas composer footer.
{/* manifest: atlas-safe-mode-gates-every-product-write-from-an-explicit-p */}
## Atlas
Meet Atlas, your in-app copilot for building and monitoring agents. Ask how an agent performed this week, how that compares to last week, or where customers are dropping off. Ask for a change to the agent and Atlas makes it.
Atlas holds a single conversation as you move around the product, so you never have to re-explain what you are working on. You can watch it think: a live activity line shows the tools it is calling and the reasoning behind each step.
Anything you find yourself asking repeatedly can become a Skill. Save your own in **Settings → Skills**, then pick them from Atlas whenever you need them.
Atlas is in Beta, available on agentic projects, and its usage is broken out in your workspace usage charts.
{/* manifest: atlas-the-builder-ai-assistant-rebuilt-as-a-persistent-panel */}
## Markdown source view
The fullscreen global prompt and playbook instruction editors can now be switched to their markdown source and edited as plain text, so you can see and change exactly what the agent will read. Use **Show markdown source** in the floating actions, and **Show rendered markdown** to switch back.
Source mode has syntax highlighting and tab indentation, and your choice is remembered per editor. The rendered view is still the default, so nothing changes unless you switch. Copying from the rendered view now gives you markdown.
{/* manifest: a-markdown-source-view-in-the-global-prompt-and-playbook-ins */}
## Transcript keyword search
You can now find transcripts by what was actually said in them. Search for a phrase and the list narrows to conversations containing it, with each result showing how many messages matched and a short excerpt around the first hit.
You can also narrow to just what the user said, or just the agent. Search terms can be up to 256 characters, and the same filter is available on the transcript search API.
{/* manifest: transcripts-can-be-searched-by-keywords-in-user-and-agent-me */}
## Max conversation duration
Voice conversations can now run up to sixty minutes, double the previous ceiling. You can set the limit from **Behaviour → Session & timeout**.
Agents that had the setting switched off move to a thirty-minute default. If you previously entered a value above thirty minutes, note that it was silently capped before and will now apply in full.
{/* manifest: max-conversation-duration-is-always-on-set-with-a-slider-and */}
## MCP token authentication
The Voiceflow MCP server now accepts a personal access token as a bearer credential, so a client that cannot open a browser for OAuth can connect using the same token that authenticates the REST API and the CLI. Send it in the `Authorization` header instead of completing the browser sign-in. The OAuth flow is unchanged.
{/* manifest: the-voiceflow-mcp-server-accepts-a-personal-access-token-ins */}
## Trace filtering on the conversation endpoint
A caller of the stable conversation endpoint can now list trace types to drop from the response, so an integration only receives the traces it renders. Send a `config` object alongside the action with `excludeTypes` listing the types to drop. Omit it and every trace comes back as before.
One trace is always returned even when its type is excluded: the debug trace reporting that the credit limit was reached.
{/* manifest: trace-types-can-be-excluded-from-the-stable-conversation-end */}
## Late variable writes
A variable set after the agent has already replied, which is the normal case for an asynchronous tool that finishes late, now survives into the following turn instead of being quietly reverted. The agent reads what was actually written.
Nothing to configure. If your agent was built to expect late writes to be discarded, note that it will now see the updated values instead.
{/* manifest: a-variable-written-after-a-turn-is-sealed-is-no-longer-rever */}
## Multilingual Cartesia voices
Cartesia text-to-speech now covers over forty languages, up from fifteen. Each voice declares which languages it speaks, and the preview sample plays in the language you selected. Choose a provider, voice and language from **Settings → Behaviour → Voice output**.
The voice menu now filters by language, so a voice that does not support the language you pick will not appear in the list. Existing selections are untouched.
{/* manifest: cartesia-voices-support-forty-languages-with-samples-that-pl */}
## Knowledge base logs in evaluations
**Knowledge base logs** joins Playbook, Workflow and Tool logs in an evaluation's **Log visibility** settings. With it on, the evaluating model can see the knowledge base searches your agent ran, so a criterion about whether an answer came from your content is something it can actually check. As with the other log types, including them makes each prompt longer and raises the average cost per evaluation.
{/* manifest: an-evaluation-can-be-given-the-agent-s-knowledge-base-search */}
## Transcript environment fields
A transcript fetched from the REST API now reports which environment the conversation ran in, and whether it ran against the draft or published version. Both fields are null for conversations recorded before environments existed.
{/* manifest: transcripts-from-the-stable-rest-api-carry-their-environment */}
## Live agent typing indicator
When a live agent is composing a reply during a handoff, the user now sees that the agent is typing instead of waiting in silence.
Nothing to configure. This currently applies to handoffs to Dixa; other providers are unchanged.
{/* manifest: a-typing-indicator-while-a-live-agent-is-replying-during-a-h */}
## Parallel tool calls
When an agent makes several tool calls in a single turn, all of them now run and every result comes back. Previously all but the last were discarded, so an agent that searched the knowledge base three times answered from one search.
Nothing to configure. This covers every kind of tool call an agent makes in a turn, including knowledge base searches, API tools, functions and integrations. Each result is matched back to the call that asked for it, and turns that make several calls are faster.
{/* manifest: more-than-one-knowledge-base-search-in-a-single-turn-no-long */}
## Tool message traces
The message an agent speaks while a slow tool runs now reaches applications that call the API without streaming. It arrives as an ordinary `text` trace for chat or a `speak` trace for voice, generated through the same path as any other agent message. Previously it was dropped.
Nothing to configure. If your integration consumes completion events, it keeps receiving the message as a completion sequence. If it does not, responses from non-streaming endpoints now carry one additional trace.
{/* manifest: a-generated-tool-call-message-reaches-callers-that-do-not-co */}
## Out-of-credit call handling
Phone calls are now declined when your organization has run out of credits, instead of connecting to an agent that cannot respond. The caller hears that no agents are available. A test call from the builder tells you to add credits.
Organization admins are emailed when this occurs.
{/* manifest: voice-calls-are-declined-when-the-organization-has-run-out-o */}
## Personal access tokens
You can now create a personal access token with an expiry you choose, and use it in place of the shared project API key for Voiceflow's APIs and the CLI. Create and revoke tokens from **Settings → Access tokens**. Project API keys will keep working.
Pick an expiry when you create a token, and copy the value once. A searchable table lists your tokens with their expiry and the actions available for each.
{/* manifest: personal-access-token-management-page-with-project-api-keys- */}
## Live transcripts
You can now follow a conversation while it is still in progress. Open **Transcripts** and click a conversation that has not ended, and each turn appears as it happens while the view scrolls itself, so you no longer have to wait for a conversation to finish before you can read it.
The view refreshes every four seconds and pauses while the browser tab is in the background. Once the conversation closes it keeps listening briefly so the final message still arrives, then settles.
{/* manifest: a-transcript-for-a-conversation-still-in-progress-follows-it */}
## Tag tools, playbooks, and workflows in your instructions
You can now reference a resource directly instead of naming it in plain text. Press `/` in the global prompt, agent instructions, or playbook instructions, choose a type (playbook, workflow, system tool, or tool), then pick from your project. It's inserted as a chip bound to that resource. Variables continue to be referenced using `{`.
If a tagged resource isn't available in that context, the chip flags it rather than silently failing.
## Markdown editor
The global prompt, agent instructions, and playbook instructions now use a Markdown editor. Structure your instructions with headings, lists, bold and italic, either with standard Markdown shortcuts (`## ` for a heading, `**bold**`, `> ` for a quote) or by pressing `/` to open the formatting menu. Agents built from a prompt come back formatted this way by default.
Existing instructions migrate automatically. The underlying data is unchanged, only how it's rendered and edited.
## Widget width
You can now set the chat widget's width from Interface → Widget, instead of overriding the `vfrc-chat` class with custom CSS. Minimum is 320px, and the widget stays responsive if the width you set exceeds the browser window.
{/* manifest: the-chat-widget-s-width-is-a-setting-instead-of-a-custom-css */}
## Session lifecycle webhook: richer payloads, `.v2` events deprecated
All four session lifecycle events (`runtime.session.start`, `runtime.session.end`, `runtime.call.start` and `runtime.call.end`) now carry the metadata that previously appeared only on their `.v2` variants: `versionID`, `transcriptID`, `versionVariant`, `projectEnvironmentID` and `projectEnvironmentAlias`, plus `endReason` on `runtime.session.end` and `sessionID` on the call events. `sessionID` on call events is new information: call and session events can now be correlated with each other for the first time.
These fields are **optional and nullable**. The `.v2` events only fired when every one of them was known, whereas the standard events fire on every session and call, so your handler should tolerate `null`. `versionID` carries the same value as `environmentID`.
**Deprecation:** `runtime.session.start.v2`, `runtime.call.start.v2` and `runtime.call.end.v2` will **stop firing on October 9, 2026**. Until then they continue to be delivered alongside their replacements, so you can migrate at your own pace. Switch to the event name without the `.v2` suffix.
`runtime.session.end.v2` has been removed. It never fired, because its trigger condition depended on data that was never recorded, so it had no subscribers.
We've also clarified a point that causes recurring confusion: session events fire on **every channel**, chat included. A voice conversation emits both `runtime.call.*` and `runtime.session.*` because a call and a session are different things with different end conditions. See [Session lifecycle webhook](/docs/api-reference/webhooks/session-lifecycle) for the full breakdown.
## Soniox speech to text model
Voiceflow now supports Soniox's V5 real-time speech to text model.
## Generative tool messages
In addition to scripted tool messages, you can now provide generative tool messages that use the conversation history to provide a contextually correct tool message at that point in the conversation. You can accompany generative tool messages with examples as hints for how your agent should reply. Generative tool messages also work nicely in multilingual agents and will reply in the language of the current conversation.
## Handoff configuration
A Live agent handoff step's **Configuration** field now controls the wait-time message and can hide file upload for the duration of a handoff. `waitTimeMessage` takes None, Delay, Time or Position; a mode your provider cannot render falls back to that provider's default rather than turning the message off. `disableFileUpload` hides the widget's upload control, and it stays hidden if the visitor reopens the chat.
Variables can now be written into the Configuration JSON the normal quoted way without voiding the rest of the object, and an invalid key drops only itself rather than the whole object. If you use Kustomer, Genesys, Ujet or Dixa, note that this changes what an untouched step sends to them.
{/* manifest: live-agent-handoff-step-gains-a-configuration-field-with-wai */}
## Project Analytics Updates
We made it easier to understand your agent's performance and ROI, by introducing a summary section on the **Analytics** page. Key evaluations and metrics now sit at the top: resolution rate and customer satisfaction are surfaced by default, alongside total conversations, spend, and average cost per conversation.
A number of new metrics were also added. This includes:
- LLM Cost
- TTS Cost
- SST Cost
## Environment Protection
You can now lock down individual environments so only admins or owners can publish or merge into them. Turn on **Environment protection** from the environment's ••• menu in **Settings → Environments**. Everyone else keeps their normal access to build and test - they just can't merge changes into that environment.
This is most useful on Main and on any environment carrying live traffic. Anyone can still create a new environment, this protects production environments from accidental or unauthorized changes.
## Cost limit per conversation
You can now set a maximum spend per conversation. Define a dollar amount, and once a session's cost exceeds it, Voiceflow ends the session automatically - a hard ceiling on any single conversation, no matter how long it runs or how many tools it calls.
For voice calls, this pairs with Max conversation duration: duration caps how long a conversation lasts, while cost limit caps what it spends. A short conversation that hammers an expensive model can cost more than a long, quiet one, so the two guardrails catch different failure modes.
As with duration, you can set an optional **End message** that's sent before the session closes.
This setting is off by default. Find it in **Settings → Behaviour.**
## Max conversation duration for phone calls
You can now cap how long a single conversation is allowed to run. Set a limit in seconds, and once a conversation hits it, Voiceflow ends it automatically - so a caller who stays on the line indefinitely, or an agent stuck in a loop, can't quietly burn through credits.
You can also define an optional **End message** that plays before the conversation closes, so the user gets a graceful sign-off instead of a dropped call.
This setting is off by default. Find it in **Behaviour → Session & timeout**.
## File upload in chat widget
The chat widget now natively supports file and image uploads for both AI agent and human handoff conversations. To turn file uploads on, open **Widget → Modality & Interface** and enable **Allow file attachments**.
Users can upload up to 10 files during a conversation. Supported file types include PDF, JPEG, JPG, PNG and WEBP.
Files are stored in a secure Voiceflow storage repository and are never publicly accessible. [Learn more](https://docs.voiceflow.com/documentation/deploy/widget/custom-web-chat-styling#enabling-file-uploads)
## Improvements to tool call sounds
Tool call sounds now:
1. Have manual volume control
2. Include more sound options
3. Automatically decrease volume when agent it talking over it
4. Fade in and out to create a more natural dialog
## Background audio for all telephony providers
All Telephony providers (Voiceflow, Twilio, Vonage, Telnyx) now support background audio. Background audio configuration can be found in the behaviour tab of your project.
## Secrets conflict resolution
When merging an environment into Main, Voiceflow detects secrets whose values differ between the two environments. Before the merge completes, you choose how to resolve them: keep Main's existing values (default), or enable **Override Main secrets** to replace them with the incoming environment's values. This prevents merges from silently overwriting production credentials - like API keys pointed at staging systems - without an explicit decision.
## Evaluations with log visibility
Evaluations just got a lot more observant. With the new **Log visibility** setting, you control exactly what your evaluating model can see when it scores a transcript - going beyond the conversation itself and into what your agent actually _did_ behind the scenes.
Choose which logs to include in each evaluation:
- **Playbook logs** - see which playbooks fired and how they reasoned toward their goal
- **Workflow logs** - trace the deterministic steps a conversation passed through
- **Tool logs** - inspect every tool call, input, and response
Each log type is opt-in, so you stay in control of the trade-off: more logs give the evaluating model richer context, while fewer logs keep credit usage lean. Enable all three, mix and match, or include none - whatever fits the question you're trying to answer.
## Variable persistence control
You can now control whether individual variables persists across user sessions. Define what should carry across sessions (name, preferences, tier) for returning users, and ignore what shouldn't. [Learn more](https://docs.voiceflow.com/documentation/build/data/variables#persisting-variables-across-sessions)
## Required variables for workflows & playbooks
Specify variables that must be filled before a playbook or workflow can be routed to. Until every required variable has a value, the agent won't hand off to it.
## Entry conditions
You can now gate playbooks and workflows behind entry conditions - deterministic checks that must evaluate to true before the agent can access that playbook or workflow. If the conditions aren't met, the playbook/workflow stays unavailable for routing, giving you precise, rule-based control over when each one becomes reachable.
## Organization level usage breakdown
You can now see exactly where your spend is going from a birds eye view. Usage breakdowns now include spend across workspaces and projects, broken down by Runtime, Measure, Development, and Generation features. Drill into a specific workspace, project, or date range to track costs over time and understand what's driving them.
## Transcript filtering by workflow, playbook and tool usage
You can now filter transcripts by a specific workflow, playbook, or tool and see only the conversations where it was used.
## Caller ID passthrough
When using the Call forward system tool, the forwarded destination can now see the original caller's number. This can be helpful to ensure your contact center platform receives accurate caller information for routing, logging, and CRM matching.
## Save tool responses to properties
Tool outputs can now be saved to [properties](https://docs.voiceflow.com/documentation/measure/transcripts#attaching-custom-properties), not just variables. Previously, when an agent called a tool, you could capture the response to a Voiceflow variable - now you can map it to a property as well, which is useful for tracking and transcript tagging.
## Merge conflict awareness
When merging an environment back into main, you can now see whether main has changed since you branched off it. This makes it clear when your branch is working from an outdated version of main, so you can review and reconcile those changes before merging.
## Personas
Personas let you test conversations with specific variable values already in place. They’re useful for testing how your agent handles different customer types or account states without setting things up by hand each time. [Learn more](/docs/documentation/build/data/personas)
## Tests
Tests let you verify your agent’s behaviour before real users see it. Each test simulates a conversation between a user and your agent, then checks that things like the agent’s responses, where it routed, and which tools it called match what you expected. [Learn more](/docs/documentation/measure/tests)
## Project converter
You can convert a chat project to voice (or voice to chat) right from your workspace dashboard. Select the project, click the ellipsis (•••) button, and choose **Convert to voice** or **Convert to chat**.
## Query re-writing
When enabled, the model rewrites the user’s last message before searching based on your instructions - improving retrieval for conversational or ambiguous inputs. Useful when users don’t phrase questions the way your content is written. [Learn more](https://docs.voiceflow.com/documentation/build/querying-the-knowledge-base#query-re-writing)
## New model: Voiceflow Core
Voiceflow Core is our first model, optimized for the kinds of tasks agents actually do - tool calling, multi-turn reasoning, instruction following inside playbooks. We benchmarked it on Voiceflow's agentic framework against the models we currently support (Anthropic, OpenAI, Gemini) and saw stronger quality, at a lower per-token cost. Core is rolling out as a selectable model across all plans.
## Pronunciation dictionaries
The pronunciation dictionary rewrites words or phrases in your agent’s responses before they’re sent to text-to-speech. This ensures correct pronunciation of names, places, or technical terms. You can find this setting in Behaviour/Voice Output/Pronunciation dictionary. [Learn more](https://docs.voiceflow.com/documentation/build/behaviour#pronunciation-dictionary)
## Environments
Work on multiple versions of your agent in parallel, conduct A/B tests with traffic splits, and roll changes back with confidence. [Learn more](/docs/documentation/deploy/environments/overview)
## Tool call sounds
You can now play an audio snippets while a tool call is running, so users aren't sitting in dead air during longer-running tools. Pick from sounds like keyboard typing, elevator music, and others directly in the tool call configuration.
This is a voice specific feature, so it's only available on voice projects.
## Evaluation preview cards
Evaluation results now open with summary cards at the top of the page, so you can see the key numbers at a glance without digging into the details.
## Flux multilingual
Flux Multilingual extends Flux to 10 languages. We highly recommend switching to Flux as it's the most performant STT model in market.
## Skip turn system tool
The skip turn tool lets the agent stay quiet and wait for the user instead of replying. Use it when the user asks for a moment - things like "hold on," "give me a sec," "let me think," or "one moment" - so the agent doesn't talk over them or fill the pause with something unnecessary.
## New default properties for chat transcripts
Chat transcripts now include OS, Device, Browser & Country properties by default. You can also filter your transcripts or evaluation results by any of these properties.
## Shopify tools
Connect your Shopify store to Voiceflow in a couple of clicks and give your agent instant access to real order and product data - no custom API wiring required.
What your agent can now do out of the box:
- **Answer product questions with live data** - stock levels, sizing, variants, and specs pulled straight from your catalog, so customers get accurate answers instead of hallucinated ones
- **Resolve "where's my order?" without a human** - customers self-serve status, tracking, and history just by asking
- **Turn support chats into revenue** - recommend the right next product based on what the customer is already looking at or buying
- **Handle cancellations end-to-end** - refund-ready cancellations happen inside the conversation instead of in a support queue
## Native fail path on Function and API steps
You can now enable a native failure path on Function and API tool steps. When a tool responds with an error code, or times out, the failure path triggers if enabled.
- If the Failure path is disabled and the tool errors or times out, the step exits through the first available port.
- This does not apply to API or Function tools used in the global agent or playbooks - the agent handles all cases.
- If the Failure path is disabled and the tool errors or times out, the step exits through the first available port.
- This does not apply to API or Function tools used in the global agent or playbooks - the agent handles all cases.
- If the Failure path is disabled and the tool errors or times out, the step exits through the first available port.
- This does not apply to API or Function tools used in the global agent or playbooks - the agent handles all cases.
## Workflow usage
You can now see workflow usage, alongside playbook usage in analytics. If you're not immediately seeing it in your analytics view, try adding it by editing the view from the page header.
## Global tools
You can now add [API](/docs/documentation/build/tools/api-tool), [MCP](/docs/documentation/build/tools/mcp-tool), [integration](/docs/documentation/build/tools/overview) and [function](/docs/documentation/build/tools/function-tool) tools directly at the agent level, making them available across your agent.
[Global tools are available](https://docs.voiceflow.com/documentation/build/tools/global-tools#when-are-global-tools-are-available-for-my-agent-to-use) any time the user is in an agentic context.
## Custom timeouts for API and function tools
You can now configure a custom timeout on [API](/docs/documentation/build/tools/api-tool) and [function](/docs/documentation/build/tools/function-tool) tools. If a tool doesn't respond within the set limit, it times out and triggers the fail path - so any fail tool messages or fallback paths you've configured will fire on timeout as well. The default timeout is 20 seconds.
Maximum timeout limits by plan:
| Plan | Maximum timeout |
| --- | --- |
| Enterprise | 600s (10 min) |
| Business | 150s (2.5 min) |
| Pro | 150s (2.5 min) |
| Trial | 60s (1 min) |
## Live conversations indication in transcripts
Your Transcripts table just got a heartbeat. Active conversations now appear have an indicator, alongside current cost - giving you a live pulse on every session as it happens. Refresh the table to pull in the latest updates without leaving the page.
## Interact with responses while they stream
Links are now clickable and text is copyable while the agent is still generating a response - so you can act on information the moment it appears, not after the last word lands.
## Resizable conversation editor in run mode
The conversation editor in run mode can now be resized, giving you more space when you need it.
## Run mode & transcript improvements
Run mode and historical transcripts now surface three new layers of detail to make testing and reviewing your AI agents more informative:
**Agent navigation** - When routing occurs, the transcript shows the path inline (eg: _Agent → Reservations specialist)_, giving you a clear trace of how conversations are routed throughout your AI agent.
**Latency indicators** - Each agent response shows its response time in milliseconds or seconds, making it easy to spot slow steps in your flow. Hover a latency chip to see more detail.
**Input types** - User turns are tagged with how the input was received (eg: _Voice input_, _Keypad input_, _Button input_, _Text input_), so you can better understand how your customers are interacting with your agent.
## Improved evaluation filters
You can now apply more granular filters to your evaluations - making it easier to track performance trends, compare results across specific time ranges, and pinpoint where your agent is improving or regressing.
## Customize widget loader
You can now choose how your agent looks while it's thinking. Pick between a spinner with text or a minimal dots loader, and customize the loading message to match your brand. Find it under Interface → Widget. This is a chat only feature.
## Async tool response capture
API and Function tools running asynchronously can now save their response to a Voiceflow variable. Previously, async was fire-and-forget - useful for logging and side effects, but the response was lost. Now you can fire an async call, continue the conversation, and reference the result as soon as it arrives.
This unlocks predictive experiences. Fetch a customer's recent orders during authentication, pull account data while the agent greets the user, or query a slow third-party service while the conversation moves forward.
## ElevenLabs Scribe v2 Realtime STT
We’ve added support for ElevenLabs' newest and most accurate speech-to-speech model, Scribe v2 Realtime. Supporting 90\+ languages.
## Eleven v3 TTS
We’ve added support for ElevenLabs' newest and most expressive text-to-speech model, Eleven v3. Supporting 70\+ languages.
## Show source URLs in responses
When enabled, the agent includes the source URL (If public URL) alongside its response so users can verify or learn more. Recommended for help centers and documentation.
This feature is available for both the knowledge base and web search system tools.
You can set the maximum number of sources you want to show per agent message (defaulted to 1).
## Async functions and API tools
You can now run Function and API tool steps asynchronously.
Async execution allows the conversation to continue immediately without waiting for the tools to complete. No outputs or variables from the step will be returned or updated.
This is ideal for non-blocking tasks such as logging, analytics, telemetry, or background reporting that don’t affect the conversation.
Note: This setting applies to the reference of the Function or API tool - either where the tool is attached to an agent or where it’s used as a step on the canvas. It is not part of the underlying API or function definition, which allows the same tool to be reused with different async behaviour throughout your project.
## Tool messages
Tool messages let you define static messages that are surfaced to the user as a tool progresses through its lifecycle:
1. Start - Message delivered when the tool is initiated
2. Complete - Message delivered when the tool finishes successfully
3. Failed - Message delivered if the tool encounters an error
4. Delayed - Message delivered if the tool takes longer than a specified duration (default: 3000ms, configurable)
This provides clear, predictable feedback during tool execution, improving transparency and user trust - especially for long-running or failure-prone tools.
## GPT 5.2
Added global support for GPT 5.2
## Voice mode in web widget
Your web widget now supports hands-free, real-time voice conversations. Enable it from the Widget tab for existing projects - it’s on by default for new ones.
Users can talk naturally, see transcripts stream in instantly, and get a frictionless voice-first experience. It also doubles as the perfect in-browser way to test your phone conversations - no dialing in, just open the widget and run the full voice flow instantly.
## Native web search tool
We’ve shipped a native Web Search tool so your agents can look up real-time information on the web mid-conversation - no custom integrations required.
- Toggle on the web search tool in any agent to answer questions that need live data (news, prices, schedules, etc.).
- Configure search prompts and guardrails so the agent only pulls what you want it to.
- Results are summarized and grounded back into the conversation for more accurate, up-to-date answers.
- Toggle on the web search tool in any agent to answer questions that need live data (news, prices, schedules, etc.).
- Configure search prompts and guardrails so the agent only pulls what you want it to.
- Results are summarized and grounded back into the conversation for more accurate, up-to-date answers.
- Toggle on the web search tool in any agent to answer questions that need live data (news, prices, schedules, etc.).
- Configure search prompts and guardrails so the agent only pulls what you want it to.
- Results are summarized and grounded back into the conversation for more accurate, up-to-date answers.
## Telnyx telephony integration
You can now connect your Telnyx account to import and manage phone numbers directly in Voiceflow, enabling Telnyx as your telephony provider for both inbound and outbound calls..
## Native support for keypad input (DTMF)
Added native support for DTMF keypad input in phone conversations. Users can now enter digits via their phone keypad, sending a DTMF trace to the runtime. Configure timeout and delimiters (#, \*) to control when input is processed. See [documentation here](/docs/documentation/build/behaviour).
- Keypad input is off by default and can be turned on from Settings/Behaviour/Voice.
- When on in project settings, keypad input can be turned off at the step level via the "Listen for other triggers" toggle.
- [View full documentation here](/docs/documentation/build/behaviour)
- Keypad input is off by default and can be turned on from Settings/Behaviour/Voice.
- When on in project settings, keypad input can be turned off at the step level via the "Listen for other triggers" toggle.
- [View full documentation here](/docs/documentation/build/behaviour)
- Keypad input is off by default and can be turned on from Settings/Behaviour/Voice.
- When on in project settings, keypad input can be turned off at the step level via the "Listen for other triggers" toggle.
- [View full documentation here](/docs/documentation/build/behaviour)
/cde84932767adb0d81388512a5095eb21cdd6f3d9d2f7ae5ac97cb384842ec6c-CleanShot_2025-11-10_at_11.50.552x.png)
## Knowledge base metadata
Add metadata to your Knowledge Base sources to deliver more relevant, localized, and precise answers, helping customers find what they need faster and improving overall resolution speed.
1. Adding metadata on knowledge import
When uploading files, URLs, or tabular data to the Knowledge Base, you can attach metadata at import time. This metadata is stored with each document or data chunk, enabling structured filtering and contextual retrieval later. For example, when importing car rental policies, you might tag each file with metadata like "locale": "US, CA, EU", or "serviceType": "car\_rental, equipment\_rental". This ensures that when the agent queries using metadata filters (static or dynamic), it only retrieves content relevant to the user’s local region or service context.
2. Dynamically, or statically apply metadata at runtime
From the Knowledge Base tool in your agent, define the metadata your agent should use when querying the tool. You can specify a static value (or variable) to consistently filter results, or let the agent dynamically assign metadata at runtime - allowing it to query the Knowledge Base contextually based on each unique conversation.
Example - Car Booking Service
If your Knowledge Base includes information for multiple locales (eg: US, CA, EU), you can set a metadata field like locale. Instead of hardcoding a single locale, the agent can dynamically apply the user’s locale at runtime - for example:
If a user says “I want to book a car in New York,” the agent automatically filters Knowledge Base results with locale: US, ensuring responses only reference policies, pricing, and availability relevant to that locale.
## Built-in time variables
We’ve added a set of built-in time variables that make it easier to access and use time within your agents - no external API calls or workarounds required. Perfect for agents that depend on current or relative time inputs.
Project timezone can be set in project/behaviour settings:
## Deepgram Flux ASR model
We've added [Deepgram Flux](https://flux.deepgram.com/), their ASR newest model built specifically for Voice AI.
Flux is the first conversational speech recognition model built specifically for voice agents. Unlike traditional STT that just transcribes words, Flux understands conversational flow and automatically handles turn-taking.
Flux tackles the most critical challenges for voice agents today: knowing when to listen, when to think, and when to speak. The model features first-of-its-kind model-integrated end-of-turn detection, configurable turn-taking dynamics, and ultra-low latency optimized for voice agent pipelines, all with Nova-3 level accuracy.
Flux is Perfect for: turn-based voice agents, customer service bots, phone assistants, and real-time conversation tools.
Key Benefits:
- Smart turn detection - Knows when speakers finish talking
- Ultra-low latency - ~260ms end-of-turn detection
- Early LLM responses - EagerEndOfTurn events for faster replies
- Turn-based transcripts - Clean conversation structure
- Natural interruptions - Built-in barge-in handling
- Nova-3 accuracy - Best-in-class transcription quality
## Sync audio and text output
Converts text to speech in real time and keeps the spoken audio perfectly aligned with the displayed text. This ensures call transcripts are an accurate, word-for-word representation of what was actually said.
## Transcript inactivity timeout
This setting lets you define how long a conversation can stay inactive before the transcript automatically ends.
This is different from session timeout - the session stays open, but the transcript closes after the set inactivity period, enabling more accurate reporting and evaluations.
Important: ending the transcript does not end the user’s ability to re-engage. If the user responds again, a new transcript will begin within the same session.
## Priority processing for Open AI models
We’ve added a new [Priority Processing](https://openai.com/api-priority-processing/) setting for OAI-supported models. When enabled, your requests will be given higher processing priority for faster response times and reduced latency. Note: this will consume more credits.
## MCP tools
Supercharge your agents by connecting directly to MCP servers.
- 🔌 Connect to MCP servers in just a few clicks
- 📥 Add MCP server tools to your agents
- 🔄 Sync MCP servers to stay up-to-date
Bring in any tool, expand what your agents can do, and take your workflows to the next level.
[Documentation](/docs/documentation/build/tools/mcp-tool)
## Call forwarding tool in agents
You can now enable your agents to forward calls to a different number, SIP address, or extension.
- 📞 Seamlessly transfer callers to the right person or agent
- 🔀 Supports phone numbers, SIP addresses, and extensions
- 🛠️ Configure forwarding directly in your agent’s tools
This makes it easier to connect customers with the right destination without breaking the flow of the conversation.
## Control reasoning effort for supporting GPT models
We've added a reasoning effort slider for all supporting GPT models (GPT-5, GPT-5 mini, GPT-5 nano, GPT-o3 and GPT-o4-mini).
## Shareable links now match your AI agent
Shareable links have been upgraded to better reflect the agent you’re building. Each link now points to a hosted version of your AI agent that mirrors your selected environment (dev, staging, production) and interface, so what you share is exactly what others will experience. Password protection is also available for secure access.
- 🔗 Sharable links now mirror your actual AI agent
- 🛠️ Environment-specific links (dev, staging, production)
- 🎨 Customize the look and feel via the Interfaces tab
- 🔒 Optional password protection for secure sharing
## Staging environment added
We’ve introduced a new staging environment to help you manage deployments more effectively. You can now publish between development, staging, and production to test changes before going live.
- New staging environment for pre-production testing
- Publish across dev → staging → production
- More control and confidence in deployment flows
- Override secrets per environment for greater flexibility
## Duplicating projects now clones knowledge base
You can now duplicate projects along with their entire knowledge base. When cloning a project, all connected documents and data sources are copied as well - so your new project starts with the same knowledge setup as the original.
This enhancement only applies to project duplication. Knowledge bases are not yet cloned when using project import.
## Control saving of empty transcripts
You can now choose whether to save transcripts where the bot spoke but the user never replied. Use this toggle to keep your transcript logs cleaner and focused on real interactions. By default, all new projects will save all conversations to transcripts.
## Save input variables in tool calls
Previous to this release, you could only capture the output of a tool call (eg: the response from an API). Now, you can also persist the inputs (the parameters sent to the tool) as Voiceflow variables. This means both sides of the transaction - request and response - can be tracked, reused, or referenced later in the conversation.
## GPT-5 models
GPT-5 models are now available in Voiceflow.
## Double-click to open agent step
You can now double-click an agent step to jump straight into its editor - saving yourself an extra click.
## Tool step
You can now run tools outside of the agent step using the new Tool Step.
This lets you trigger any tool in your agent - like sending an email or making an API call - anywhere in your workflows.
🛠️ You’ll find the call forwarding Step in the ‘Dev’ section of the step menu for now.
Tools can also be used as actions:
## New analytics API
A few months ago, we released a new analytics view - giving you deeper insights into agent performance, tool usage, credit consumption, and more.
Today, we're releasing an updated [Analytics API](/docs/api-reference/usage/query-usage) to match. This new version gives you programmatic access to the same powerful data, so you can:
Track agent performance over time
Monitor tool and credit usage
Build custom dashboards and reports
Use the new API to integrate analytics directly into your workflows and get the insights you need - where you need them.
## Custom query control & chunk limit for knowledge base tool
You now have more control over how your agents retrieve knowledge. Customize the query your agent uses to search the knowledge base, and fine-tune the chunk size limit to better match your content. This gives you more precision, better answers, and smarter agents.
## Better transcripts. Custom evaluations. Better AI agents.
Your AI agents just got a massive upgrade:
[**🔥 What’s new**](#-whats-new)
- Transcripts, reimagined - Replay calls, debug step-by-step, filter with precision, and visualize user actions like button clicks - all in a faster, cleaner UI.
- Evaluations, your way - Define what “good” looks like with customizable evaluation templates, multiple scoring types (rating, binary, text), auto-run support, and performance tracking over time.
[**📝 Transcripts**](#-transcripts)
A full overhaul of the transcripts experience, built to help teams analyze, debug, and improve agents faster.
1. Call recordings - Replay conversations to hear how your agent performs in the real world
2. Robust debug logs - Trace agent decisions step-by-step
3. Granular filtering - Slice data by time, user ID, evaluation result, and more
4. Button click visualization - See exactly where users clicked in the conversation
5. Cleaner UI - Faster load times, more usable data
[**📊 Evaluations**](#-evaluations)
Define what “good” looks like - and measure it, your way. Build (or generate) your own evaluation criteria, tailor analysis to your business goals, and iterate with confidence.
Eval types - support for:
1. ⭐ Rating evals (eg: 1-5)
2. ✅ Binary evals (Pass/Fail)
3. 📝 Text evals (open-ended notes)
Also includes:
- Batch or auto-run - Evaluate hundreds of transcripts in a few clicks, or automatically as they come in
- Analytics & logs - See detailed results per message or overall trends over time
[**APIs**](#apis)
- We've release a brand new [Evaluations API](https://link.voiceflow.com/evals-api)
- We've release a new [Transcripts API](https://link.voiceflow.com/transcript-api) The legacy Transcripts API is still supported and currently has no deprecation timeline
🕓 Transition Period: Until September 28, 2025, all transcripts will be available in the legacy view, for existing projects. On September 28th, 2025 the old view will be hidden and the new transcripts view will be the default. Transcripts older than 60 days will still be accessible via API for the foreseeable future.
## Gmail tools: let your AI agents send emails
Agents can now send emails seamlessly as part of any conversation. Whether it’s a confirmation, follow-up, or lead nurture message - the new Send Email tool makes it easy to automate communication right from your agent. Just connect your Gmail account and you’re ready to go.
Make sure to instruct your agent on how to use this tool properly. Give it a try in the agent step!
## Call forwarding step
Seamlessly connect your voice AI agent to the real world with call forwarding.
The new call forwarding step lets your AI agent hand off calls to a real person (or another AI agent) - instantly and smoothly.
- ✅ Route to phone numbers
- ✅ Include optional extensions
- ✅ Support for SIP addresses
Build smarter, more human-ready voice agents - without sacrificing automation.
🛠️ You’ll find the call forwarding Step in the ‘Dev’ section of the step menu for now. We’re planning to introduce a dedicated voice section soon - stay tuned!
## Hubspot tools
Connect your agents to Hubspot to create contacts, leads and tickets.
## SMS messaging with Twilio tools
Enable your agents to send SMS messages with an effortless connection to Twilio. Try it now in the agent step.
## Create AI agents instantly - from just a prompt
We’ve made building AI agents dramatically faster.
You can now generate a fully-functional agent by simply describing what you want it to do. No setup. No manual flow-building. Just write a detailed prompt - and Voiceflow will generate everything for you:
✅ Agent instructions
✅ Tools and workflows
✅ Conversation logic and components
This means less time configuring, more time testing and refining your agent behavior.
Today, we’re launching:
1. Prompt-to-project generation - go from idea to working prototype in seconds
2. Prompt-to-workflow generation - describe a capability, get a complete workflow
3. Prompt-to-component generation - create specific tools and logic on the fly
This is a foundational leap in how AI agents get built on Voiceflow - we can’t wait to see what you create.
## Vonage integration for telephony
Voiceflow now supports importing phone numbers from Vonage as an alternative to Twilio. Vonage offers a minor latency improvement (~200-400ms) over Twilio, for more responsive calls.
For more information: [https://dashboard.nexmo.com/](https://dashboard.nexmo.com/) [https://www.vonage.ca/en/communications-apis/voice/](https://www.vonage.ca/en/communications-apis/voice/)
## Smarter knowledge base building with LLM chunking strategies
Your Knowledge Base just got a major upgrade. With our new LLM chunking strategies, you can now prep your data for AI like a pro - no manual formatting needed.
We’ve introduced 5 powerful strategies to help structure and optimize your content for maximum retrieval performance:
🧠 Smart chunking Automatically breaks content into logical, topic-based sections. Ideal for complex documents with multiple subjects.
❓ FAQ optimization Generates sample questions per section, perfect for creating high-impact FAQs.
🧹HTML & noise removal Cleans up messy website markup and boilerplate. Best used on content pulled from the web or markdown.
📝Add topic headers Inserts short, helpful summaries above each section. Great for longform content that needs context.
🔍 Summarize Distills each section to its key points, removing fluff. Perfect for dense reports or research.
These chunking strategies help you get more accurate, more relevant answers from your AI - especially for data sources not originally built for Retrieval-Augmented Generation (RAG).
Ready to make your Knowledge Base smarter? Try out some LLM chunking strategies and watch the results speak for themselves.
Note - LLM chunking strategies use credits. Before processing, we’ll show you a clear estimate of how many credits will be used - so you’re always in control.
## Make.com tool
Connect your agents to Make.com with a couple clicks to run your automations from your Voiceflow AI agents.
## Airtable tools
Connect your agents to Airtable with a couple clicks. Supported tools include: Create records, Delete records, Get record, List records, Update records.
## Agents can now automatically use buttons, cards, and carousels to enrich conversations
By enabling these options and providing guidance on when to use (or avoid) each special tool, your agent will intelligently enhance interactions with visual tools like buttons, cards, and carousels.
Note: these configurations are ignored during phone-based conversations, meaning it will not prohibit your ability to create multi-modal AI agents with Voiceflow.
## \[Deprecation\] Dialog Manager API Logs
Legacy `log` traces are no longer supported, which are sent when with the query parameter `?log=true`. This system has not been updated for a significant period and is out of date, especially with new steps.
`log` traces will no longer be returned, after Friday, July 4th, 2025.
This affects a small subset of users and should not impact the output or performance of an agent.
Going forward, it will be unified with a more robust `debug` trace system, along with a new debugger UI.
## New Speech-to-Text Providers
- Added Cartesia's [Ink-Whisper](https://cartesia.ai/blog/introducing-ink-speech-to-text) STT model This leverages OpenAI's whisper model, upgraded for realtime call performance Expanded language support and selection
- Added AssemblyAI [Universal](https://www.assemblyai.com/products/speech-to-text) STT model Advanced tuning options
- Added specific model selection for Deepgram STT Nova-2, Nova-3, and Nova-3 Medical
## Google Sheets tools
Connect your agents to Google Sheets with a couple clicks. Supported tools include: Add to sheet, Create new sheet, Get rows, Get sheet, Update sheet.
## Cartesia voices
We've added Cartesia to Voiceflow. You can select from over 100 new voices across two Cartesia models (Sonic 2 & Sonic Turbo).
## Added tool usage to project analytics
We've added all tool types to your projects analytics dashboard:
- Integration tools
- API tools
- Function tools
You can now see the number of times each tool has been used, along with the average latency and success/failure rate if you hover a specific tool.
## New workspace dashboard
- We've made updates to the workspace dashboard to make it easier to organize your projects, and manage your workspace.
- We've added folders, to further organize your projects. Note, if you previously used the Kanban view (deprecated), we've automatically converted swim-lanes into folders.
- Home tab (coming soon)
- Community tab (coming soon)
- Tutorials tab (coming soon)
## New navigation
We've listened to your feedback and made Voiceflow easier to navigate. It's the same Voiceflow, just faster to get around!
## Claude Opus 4 & Sonnet 4
We've added Claude Opus 4 & Claude Sonnet 4 to Voiceflow.
## Gemini 2.5 Pro & 2.5 Flash
We've added Gemini 2.5 Pro & 2.5 Flash to Voiceflow.
## Security Settings for Widget
- Ability to whitelist domains
- Ability to have a custom privacy message before users engage with your AI agent
- Ability to not save transcripts
## Generative No Reply
Use generative no-reply to dynamically re-engage users that haven't responded in a while. Responses will be contextual to the conversation.
## API Raw Content-Type select
The API (agent) tool and step now have a content-type option on POST requests with a "Raw" body. This will automatically apply the `Content-Type` header, for a quality-of-life convenience.
## Rimelabs Arcana Voices
Rimelabs recently released a new set of [Arcana](https://www.rime.ai/blog/introducing-arcana/) voices, that sound far more natural with intonations and speech patterns such as breathing, pauses.
Arcana is still under development and we are working with the Rimelabs team to improve it, we're aware of some issues with consistency and slurring of speech.
Arcana adds ~250ms of latency to the voice pipeline, roughly the same as 11labs.
In the future it may be possible to define your own voices by description, eg: "old man with hoarse southern accent"
## Krisp Noise Cancellation
[**Krisp Noise Cancellation**](#krisp-noise-cancellation)
Latency is one piece of the puzzle - but quality matters too. That’s why we’ve added [Krisp](https://krisp.ai/noise-cancellation/).
Background noise, especially speech or music, can seriously throw off voice agents. STT systems transcribe everything they hear, so voices in a coffee shop or lyrics from background music can easily get mistaken for the user’s input, leading to weird or incorrect responses. It can also confuse the agent into thinking the user isn’t done talking, delaying responses or interrupting playback. In short: noise kills both quality and speed.
All voice projects (web-voice widget and Twilio) automatically have Krisp noise cancellation applied.
[**Before Krisp:**](#before-krisp)
[**After Krisp:**](#after-krisp)
Here are two spectrograms, the upper one visualizing the audio that would be heard by STT without Krisp, and the lower one showing the audio after having been processed with Krisp.
Through our testing:
We've determined that this significantly boosts the accuracy of speech detection and transcription in noisy environments: cafes, offices, on the street, background broadcasts, etc.
Krisp noise cancellation adds ~20ms of latency to the audio pipeline, while drastically improving speech detection and transcription accuracy. This ultimately leads to faster final transcriptions, reducing overall speech-to-speech latency by ~100ms.
## Salesforce tools
We've added Salesforce tools to the agent step. You can now authenticate with Salesforce and add tools to enable your agent to get work done in Salesforce.
## Zendesk tools
We've added Zendesk tools to the agent step. You can now authenticate with Zendesk and add tools to enable your agent to get work done in Zendesk.
## Voice Keywords / Multilingual Speech-to-text
[**Keywords**](#keywords)
For voice calls we're introducing keywords. This allows your agent to understand hard to pronounce proper nouns (like product and company names), industry jargon, phrases and more. This is an optional field.
[**Multilingual**](#multilingual)
We're exposing Deepgram's latest [Nova-3](https://deepgram.com/learn/introducing-nova-3-speech-to-text-api) multilingual model as an STT option, capable of understanding and transcribing 8 different languages.
In addition, the standard English STT is being updated from Nova-2 to Nova-3, for a boost in performance.
## Introducing Voiceflow Credits: A simpler way to track usage
Today marks a significant milestone in Voiceflow's journey as we officially launch our new credit-based billing system. This update represents a fundamental shift in how you'll track, manage, and optimize your Voiceflow usage - all designed to bring greater simplicity, transparency, and predictability to your experience.
[**What's New**](#whats-new)
[**🎉 Voiceflow Credits**](#-voiceflow-credits)
We've completely overhauled our billing system, moving away from the complex token-based approach to a streamlined credit system that unifies tracking across all platform features:
- Simplified Measurement: One unified credit system for all actions (calls, messages, LLM responses, TTS)
- Predictable Costs: Clear pricing tiers that make budget planning straightforward
- Transparent Usage: Detailed visibility into exactly how your credits are being consumed
- Developer-Friendly: Messages only count toward credits when your agent is used in production - not when developing in-app or using shareable prototypes
[**📊 New Usage Dashboard**](#-new-usage-dashboard)
We've launched a brand-new Usage Dashboard that gives you comprehensive insights into your credit consumption. The dashboard allows you to:
- View your total available and used credits
- Track usage across all agents or drill down into specific ones
- Monitor editor and agent allocation
- Analyze usage patterns over time
[**💼 Enhanced Team Management**](#-enhanced-team-management)
Additional editor seats are now just \$50 per month with no complicated caps or restrictions. Add as many team members as needed, whenever you need them.
[**🏢 Business Plans (formerly Teams)**](#-business-plans-formerly-teams)
As part of this update, we're renaming our Teams plans to Business plans, with enhanced features and capabilities for enterprise customers.
[**Resources to Help You Transition**](#resources-to-help-you-transition)
We've created dedicated resources to help you understand and make the most of the new credit system:
- [What are Voiceflow Credits?](https://www.voiceflow.com/blog) - A comprehensive guide to understanding how credits work
- [Introducing Voiceflow Credits](https://www.voiceflow.com/pathways/introducing-voiceflow-credits) - Learn about the philosophy behind the change and how it benefits you
- [Credit Calculator](https://www.voiceflow.com/pathways/introducing-voiceflow-credits#calculator) - Estimate your credit needs based on your specific usage patterns
[**Frequently Asked Questions**](#frequently-asked-questions)
What do I need to do? Use our [Credit Calculator](https://www.voiceflow.com/pathways/introducing-voiceflow-credits#calculator) to understand your usage. For most users, no action is required.
Will my monthly bill increase? Most organizations will see a decrease in costs, particularly those with multiple editor seats. There are three changes to be aware of:
- Annual plans now offer a 10% discount (previously 20%)
- Editor seats now cost \$50/month with no restrictions (a price reduction)
- Business plan (formerly Teams) base tier increases from \$125 to \$150
Do credits roll over? Credits expire at the end of your subscription period. For monthly plans, unused credits don't roll over month-to-month. Annual subscribers receive all credits at once to use throughout the year.
What happens if I exceed my credit allocation? You'll receive a notification as you approach your limit. There's no automatic charging - you can choose whether to upgrade to a higher credit package.
Do messages in development count toward my credit usage? No, messages only count toward credits when your agent is used in production. Messages sent while developing in-app or when using shareable prototypes don't consume credits, giving you the freedom to build and test without worrying about credit usage.
We're committed to making this transition as smooth as possible. If you have any questions or need assistance, please reach out to [support@voiceflow.com](mailto:support@voiceflow.com).
## Support for OpenAI o3 and o4 mini
[**Added:**](#added)
- Support for OpenAI o3 and o4 mini
## Support for GPT 4.1 models
[**Added:**](#added)
- Support for GPT 4.1, GPT 4.1 mini and GPT 4.1 nano
## Minor Updates / Fixes
[**Improvements:**](#improvements)
- Voice Widget latency decreased by up to 750ms
- Voice Widget now streams with more consistent linear16@16kHz encoding
[**Fixes:**](#fixes)
- Reset memory when a new conversation is launched (launch request)
- Global no reply not working on Agent steps
- The maximum allowed length for `{userID}` in the [Dialog API](/docs/api-reference/v4interact/interact-stream) will be set to 128 characters, effective April 18th
- Unable to remove webhook URLs
- Analytics visualization UI bug
- Voice Widget always setting userID to test on transcripts
- Chat Widget no audio output after page reload
- Export variables fails when project has large number of variables
## Call Events Webhook
[**Changes:**](#changes)
- New support added to subscribe to call events via webhook, for both twilio IVR and voice widget projects [Call Events Documentation](/docs/api-reference/webhooks/session-lifecycle) Webhook system is capable of broadcasting additional events in the future
## Streaming Text in Chat Widget Now Optional
[**Changes:**](#changes)
- Added option to disable streaming text in chat widget Stream text can now be turned off in the Modality & interface settings When disabled, the full agent response will be displayed at once instead of being streamed out. Useful for situations where streaming longer messages is not desired
## Max Memory Turns Setting
Conversation memory is a critical component of the Agent and Prompt steps. Having longer memory gives the LLM model more context about the conversation so far, and make better decisions based on previous dialogs.
However, larger memory adds latency and costs more input tokens, so there is a drawback.
Before, memory was always set to 10 turns. All new projects will now have a default of 25 turns in memory. This can now be adjusted this in the settings, up to 100 turns.
For more information on how memory works, reference: [https://docs.voiceflow.com/docs/memory](/docs/documentation/build/behaviour)
## Agent Step, Structured Output Improvements, Gemini 2.0 Flash
We're excited to introduce several major updates that enhance the capabilities of the Agent step and expand our model offerings. These improvements provide more flexibility, control, and opportunities for creating powerful AI agents.
[**🧠 Agent Step: Your All-in-One Solution**](#-agent-step-your-all-in-one-solution)
The Agent step has been supercharged to create AI agents that can intelligently respond to user queries, search knowledge bases, follow specific conversation paths, and execute functions - all within a single step. Key features include:
- Intelligent Prompting: Craft detailed instructions to guide your agent's behavior and responses.
- Function Integration: Connect your agent with external services to retrieve and update data.
- Conversation Paths: Define specific flows for your agent to follow based on user intent.
- Knowledge Base Integration: Enable your agent to automatically search your knowledge base for relevant information.
For a comprehensive guide on using the Agent step, check out our [Agent Step Documentation](/docs/documentation/build/overview).
[**🎨 Expanded Support for Structured Output**](#-expanded-support-for-structured-output)
We've significantly expanded our support for structured output, unlocking more use cases and giving you greater control over your agent's responses:
- Arrays and Nested Arrays: You can now define arrays and nested arrays in your output structure.
- Nested Objects: Structured output now supports nested objects, allowing for more complex data structures.
These enhancements enable you to create more sophisticated agents that generate highly structured and detailed responses, reducing the risk of hallucinations and ensuring more accurate outputs.
[**⚡ Gemini 2.0 Flash Support**](#-gemini-20-flash-support)
We've added support for the Gemini 2.0 Flash model, offering you even more options for powering your AI agents. Gemini 2.0 Flash delivers exceptional performance and speed, enabling faster response times and improved user experiences.
To start using Gemini 2.0 Flash, simply select it from the model dropdown when configuring your Agent step.
We can't wait to see what you'll build with these new features and capabilities! As always, we welcome your feedback and suggestions as we continue to improve our platform.
Happy building! 🛠️
The Voiceflow Team
## Variable Handling Update: Consistent Behavior for Undefined Values
[**Changes:**](#changes)
- Updated Voiceflow variable handling for consistency in previously undefined behavior: Variables can be any JavaScript object that is JSON serializable. Any variable set to `undefined` will be saved as `null` (this conversion happens at the end of the step, so it does not affect the internal workings of JavaScript steps and functions). Functions can now return `null` (rather than throwing an error) and can no longer return `undefined` (which could cause agents to crash). Functions that attempt to return `undefined` will now return `null` (to ensure backwards compatibility).
These changes will go info effect March 31st.
## New Analytics Dashboard: Gain Deeper Insights into Your Agent's Performance
We've revamped our Agent Analytics Dashboard, not only giving it a fresh new look but also introducing a range of powerful visualizations that provide unprecedented visibility into your agent's performance.
[**🌟 New Visualizations**](#-new-visualizations)
The updated Analytics Dashboard offers a comprehensive set of visualizations that allow you to track and analyze various aspects of your agent's performance:
- Tokens Usage: Monitor AI token consumption over time across all models, giving you a clear picture of your agent's token utilization.
- Total Interactions: Keep track of the total number of interactions (requests) between users and your agent over time, providing insights into engagement levels.
- Latency Monitoring: Measure the average response time of your agent to ensure optimal performance and identify any potential bottlenecks.
- Total Call Minutes: Gain visibility into the cumulative duration of voice calls in minutes, helping you understand the volume and significance of voice interactions.
- Unique Users: Identify the count of distinct users interacting with your agent over time, allowing you to track adoption and growth.
- KB Documents Usage: Analyze the frequency of knowledge base document access, with the ability to toggle between ascending and descending order to identify the most or least used documents.
- Intents Usage: Visualize the distribution of triggered intents, with sorting options to analyze intent frequency and identify popular or underutilized intents.
- Functions Usage: Monitor the frequency of function calls, their success/failure and latency, with sorting capabilities to identify the most or least used functions and optimize your agent's functionality.
- Prompts Usage: Gain insights into the usage frequency of agent prompts, with the ability to toggle between ascending and descending order to analyze prompt utilization and effectiveness.
[**📅 Data Availability**](#-data-availability)
Please note that the new Analytics Dashboard service only has data starting from February 9th, 2025. If you require data prior to that date, you can still access it through our Analytics API.
[**🔧 Upcoming Analytics API Update**](#-upcoming-analytics-api-update)
We're also working on a new version of the Analytics API that will include the additional data points tracked by the new Analytics Dashboard service. Stay tuned for more information on this exciting update!
## New Models, Function Editor Enhancements, and Call Recording
We're thrilled to announce several exciting updates that expand your AI agent building capabilities and improve your workflow. Let's dive into what's new!
[**🧠 New Models: Deepseek R1, Llama 3.1 Instant, and Llama 3.2**](#-new-models-deepseek-r1-llama-31-instant-and-llama-32)
We've expanded our model offerings to give you even more options for creating powerful AI agents:
- Deepseek R1: Harness the potential of Deepseek's R1 model for enhanced natural language understanding and generation.
- Llama 3.1 Instant: Experience lightning-fast responses with the Llama 3.1 Instant model.
- Llama 3.2: Leverage the advanced capabilities of Llama 3.2
These new models are available on all paid plans.
[**⚙️ Function Editor Enhancements: Modal View and Snippets**](#️-function-editor-enhancements-modal-view-and-snippets)
We've made some significant improvements to the Function Editor to streamline your development process:
- Modal View: You can now open the Function Editor as a modal directly from the canvas. This allows you to make quick updates and navigate between your functions and the canvas seamlessly.
- Snippets: We've introduced a new snippets feature that enables you to insert pre-written code snippets for common concepts in Voiceflow functions.
[**📞 Call Recording for Twilio Phone Calls**](#-call-recording-for-twilio-phone-calls)
We're excited to introduce call recording functionality for phone calls made through Twilio:
- Automatic Call Recording: All phone calls between users and your AI agent will now be automatically recorded.
- Twilio Integration: The call recordings will be accessible directly in your Twilio account for easy review and management.
You can enable this option in the Agent Settings page under Voice.
## Retrieval-Augmented Generation (RAG) for Intent Recognition
We're excited to announce a significant upgrade to our intent recognition system, moving from the traditional Natural Language Understanding (NLU) approach to Retrieval-Augmented Generation (RAG) model using embeddings. This transition brings notable improvements to the speed, accuracy, and overall user experience when interacting with AI agents on our platform.
[**📅 Phased Rollout**](#-phased-rollout)
To ensure a smooth adoption, we will be rolling out the RAG-based intent recognition system to all users in phases over the next week. This gradual deployment allows us to monitor performance and gather feedback while providing ample time for you to adjust to the new system.
[**🆕 Default for New Projects**](#-default-for-new-projects)
For all new projects created on our platform, the RAG-based intent recognition will be the default system. This means that new AI agents will automatically benefit from the enhanced speed, accuracy, and natural conversation capabilities offered by RAG.
[**🌟 Faster Training and Interaction**](#-faster-training-and-interaction)
With the new RAG system, agent training and intent recognition are now substantially faster and more efficient. For example, an agent with 37 intents and 305 utterances now trains about 20 times faster, in just around 1 second. This means quicker agent development and smoother conversations for end-users.
[**🧠 Automatic Agent Training**](#-automatic-agent-training)
Thanks to the advanced training speed enabled by RAG, explicit training is no longer necessary. Simply test your agent, and the training will happen automatically behind the scenes, streamlining your workflow.
[**🎯 Enhanced Understanding of Complex Queries**](#-enhanced-understanding-of-complex-queries)
RAG leverages embeddings to capture the deeper context and meaning behind words, even when phrased differently. This allows the system to better understand and accurately match complex, detailed questions to the appropriate intents, providing more precise responses to users.
[**🗣️ More Natural Conversations**](#️-more-natural-conversations)
With the improved understanding of casual language, slang, and diverse phrasing, the RAG system enables a more natural, conversational experience for users interacting with AI agents on our platform.
[**🔄 Seamless Transition for Existing Projects**](#-seamless-transition-for-existing-projects)
For existing projects, we will keep both the NLU and RAG systems running concurrently for a period of time. This allows you to explore the new system, test it thoroughly, and make any necessary adjustments to your agents. You can easily switch between the NLU and RAG systems in the intent classification settings within the Intents CMS.
We're thrilled to bring you this enhanced experience and look forward to hearing your feedback as you interact with the new RAG-based intent recognition system. Your input is invaluable in helping us continue to innovate and improve our platform to better serve your needs.
_for_Intent_Recognition/57c510d9a8056fb12195a4bb1522dd15694b942f794421db4bdba86b9af825e7-CleanShot_2025-02-27_at_10.55.212x.png)
## Expanding the Possibilities of User Interaction with Voice
In our mission to redefine how users interact with AI agents, we have introduced a new voice modality option to our web widget. This addition is a step towards creating more natural, intuitive, and engaging user experiences. By enabling voice-based conversations, we are empowering businesses to connect with their customers in a way that feels authentic and effortless.
Voice technology has become an increasingly popular and preferred mode of interaction for many users. By integrating voice functionality into our web widget, we are meeting users where they are and providing them with a seamless way to engage with AI agents. This not only enhances the user experience but also opens up new possibilities for businesses to assist, inform, and guide their customers throughout the customer journey.
[**Natural Voice Interaction**](#natural-voice-interaction)
The web widget now supports voice-based communication, allowing users to speak naturally with AI agents. Businesses can integrate this feature to provide their customers with a hands-free, intuitive way to ask questions, receive recommendations, and get assistance while browsing the site.
[**Customization Options**](#customization-options)
The voice widget offers customization options to ensure seamless integration with your website's branding:
- Launcher Style: Select a launcher style that complements your site's design.
- Color Palette: Choose colors that match your brand guidelines.
- Font Family: Pick a font that aligns with your website's typography.
These options allow you to maintain a consistent brand experience across all customer touchpoints.
[**Powered by Advanced Voice Tech**](#powered-by-advanced-voice-tech)
The voice functionality in the widget leverages the best in voice technologies to deliver high-quality conversations:
- Automated Speech Recognition: Our platform uses advanced STT technology from Deepgram to accurately transcribe user speech in real-time.
- Organic Text-to-Speech: We've integrated with leading providers like 11 Labs and Rime to offer a variety of natural-sounding voices that bring AI agents to life.
These technologies ensure that conversations with AI agents feel authentic, engaging, and representative of your brand's personality.
[**Start Exploring Voice**](#start-exploring-voice)
We invite all our users to start experimenting with the voice capabilities.
As you explore voice functionality, we value your feedback and ideas s- join our Discord community! Your input plays a crucial role in shaping the future of voice-based interactions in the web widget and helping us refine the user experience.
## AI Fallback
We're excited to introduce AI Fallback, a powerful new feature in beta that enhances the reliability and continuity of your AI operations. This feature ensures your AI services remain operational even during provider outages or service interruptions.
[**🔄 Automatic Fallback Switching**](#-automatic-fallback-switching)
AI Fallback automatically switches between models when issues arise. When your primary AI model experiences difficulties, the system seamlessly transitions to your configured backup model, ensuring continuous operation of your AI services.
[**⚙️ Easy Configuration**](#️-easy-configuration)
Setting up AI Fallback is straightforward:
1. Access your agent
2. Navigate to agent settings
3. Set your preferred fallback model by provider
That's all there is to it! The system handles everything else automatically.
[**📈 Enhanced Reliability**](#-enhanced-reliability)
AI Fallback delivers key benefits:
- Minimizes service disruptions during model outages
- Maintains consistent AI performance
- Reduces operational impact of provider issues
- Ensures business continuity
[**🔬 Under the Hood**](#-under-the-hood)
The system continuously monitors your primary AI model's performance and availability. When issues are detected, it automatically:
- Identifies the next available model in your sequence
- Switches ongoing operations to the backup model
- Returns to the primary model once issues are resolved
[**🚀 Getting Started**](#-getting-started)
AI Model Fallback is available exclusively for Teams and Enterprise customers. We're excited to hear your feedback during the beta phase! 🎯
## New Features: Structured Outputs and Variable Pathing
Today we're introducing two powerful new capabilities in Voiceflow: Structured Outputs and Variable Pathing. These features expand the possibilities for working with data from large language models (LLMs) in your agents. Let's explore what they enable!
[**🎉 Structured Outputs**](#-structured-outputs)
Structured Outputs let you define the format of the data you expect an LLM to return, giving you more control and predictability over the results.
- In a prompt step, enable the new "JSON Output" option to specify the structure of the LLM's response.
- Today, Structured Outputs support the following data types: String Number Boolean Integer Enum
- Support for arrays and nested objects is planned for the near future.
- Structured Outputs are available with `gpt-4o-mini` and `gpt-4o` models.
[**💪 Variable Pathing**](#-variable-pathing)
Variable Pathing provides a streamlined way to work with complex data structures in your Voiceflow project.
- Store an entire object in a single variable, then access its properties using dot notation (eg: `user.name`, `user.email`).
- Capture Structured Output responses or API results as objects.
- Use object properties directly in conditions, messages, and other steps.
- Reduce the need for multiple variables to represent a single entity.
[**🍰 Bringing it All Together**](#-bringing-it-all-together)
Combining Structured Outputs and Variable Pathing opens up new design patterns for crafting agent experiences:
- Define precise data requirements for LLMs to provide relevant information
- Capture responses as feature-rich objects in a single step
- Access and manipulate object properties throughout your project
- Streamline your project's design while expanding its capabilities
We're excited to see the voice experiences you create with these new tools! Feel free to share your questions and feedback with us.
## Voiceflow Telephony
We're excited to announce the release of Voiceflow Telephony, bringing enterprise-grade voice capabilities to your conversational experiences. This release represents a significant milestone in our mission to provide comprehensive, low-latency voice solutions for businesses of all sizes.
[**Native Twilio Integration**](#native-twilio-integration)
We've integrated with Twilio to make phone-based interactions as simple as possible. The new integration allows you to:
- Import existing Twilio phone numbers directly into Voiceflow
- Associate phone numbers with specific agents
- Configure separate numbers for development and production environments
- Test different versions of your agent against different phone numbers
Setting up telephony is straightforward: simply connect your Twilio account with existing phone numbers, import them into Voiceflow, and assign them to your agents. Your voice experience will be live within minutes.
[**High-Performance Voice**](#high-performance-voice)
[**Streaming Technology**](#streaming-technology)
We've built our telephony feature on top of our streaming API, delivering exceptional performance improvements:
- Dramatically reduced response times
- Near real-time agent reactions
- Optimized voice processing pipeline
[**Speech Recognition**](#speech-recognition)
We've selected Deepgram to provide industry-leading Speech To Text (STT):
- High-accuracy transcription
- Low-latency processing
- Support for over 20 languages
[**Advanced Voice Capabilities**](#advanced-voice-capabilities)
[**Outbound Calling**](#outbound-calling)
We've introduced powerful outbound calling capabilities:
- Programmatically initiate calls to any phone number
- Test outbound calls directly from the Voiceflow interface
- Integrate outbound calling into your existing workflows
[**Voice Technology Stack**](#voice-technology-stack)
Our comprehensive voice stack includes:
- Premium text-to-speech voices from industry leaders, such as: ElevenLabs Rime Google
- Support for advanced telephony features through custom actions: Call forwarding DTMF handling Interruption behaviour
[**Voice Experience Configuration**](#voice-experience-configuration)
We've exposed detailed configuration options to fine-tune your voice experiences:
[**Audio Settings**](#audio-settings)
- Background audio customization
- Audio cue configuration
[**Interaction Parameters**](#interaction-parameters)
- Interruption threshold controls
- Utterance end detection
- Response timing optimization
- User input acceptance timing
[**Beta Program Details**](#beta-program-details)
[**Access and Limitations**](#access-and-limitations)
During the beta period, all users will have access to telephony features with the following concurrent call limits:
[**Coming Soon**](#coming-soon)
- Enhanced call analytics and reporting
- Additional voice customization options
## New AI-Native Webchat
We're excited to announce a complete reimagining of the Voiceflow webchat experience. This new version introduces AI-native capabilities, enhanced customization options, and flexible deployment methods to help you create more engaging conversational experiences.
[**AI-Native**](#ai-native)
Our webchat has been rebuilt from the ground up to provide a more natural, AI-driven conversation experience:
- Streaming Text Support: Experience real-time message generation with character-by-word streaming, creating a more engaging and dynamic conversation flow. Users can see responses being crafted in real-time, similar to popular AI chat interfaces.
- AI Disclaimers: Built-in support for displaying AI disclosure messages and customizable AI usage notifications to maintain transparency with your users.
[**Enhanced Customization**](#enhanced-customization)
We've significantly expanded the customization capabilities to give you more control over your chat interface:
[**Interface Types**](#interface-types)
You can now choose from three distinct interface modes:
- Widget: Traditional chat window that appears in the corner of your website
- Popover: Full-screen chat experience that overlays your content
- Embed: Seamlessly integrate the chat interface directly into your webpage layout
[**Visual Customization**](#visual-customization)
The new version introduces comprehensive styling options:
- Color System: Expanded colour palette support with primary, secondary, and accent colour definitions
- Typography: Custom font family support
- Launcher Variations: Classic bubble launcher with customizable icons Button-style launcher with text support
[**Important Notes**](#important-notes)
- Chat Persistence: Now configured through the snippet rather than UI settings.
- Custom CSS: Maintained compatibility with most existing class names.
- Proactive Messages: Temporarily unavailable in this release, with support coming soon
You can find more details [here](/docs/documentation/deploy/widget/embedding-the-chat-widget).
[**Migration**](#migration)
For detailed instructions on migrating from the legacy webchat, please refer to our [Migration Guide](/docs/documentation/deploy/widget/embedding-the-chat-widget).
## Function libraries, starter templates and ElevenLabs support
[**Function Libraries**](#function-libraries)
Integrate your agent with your favorite tools using our new function libraries. Access pre-built functions for popular platforms like Hubspot, Intercom, Shopify, Zendesk, and Zapier. These functions, sourced from Voiceflow and the community, make it easier than ever to connect Rev with your existing workflows. Showcase readily available integrations to your team and clients.
[**Transcript Review Hotkeys**](#transcript-review-hotkeys)
Reviewing transcripts just got faster and more efficient. You can now press `R` to mark a transcript as Reviewed or `S` to Save it for Later. These handy shortcut keys are perfect for power users who review a high volume of transcripts.
[**Project Starter Templates**](#project-starter-templates)
Getting started is now a breeze. When creating a new project, choose from a set of templates tailored for common use cases like customer support, ecommerce support, and scheduling. These templates help you hit the ground running without the need for extensive setup and customization. Ideal for new users and busy teams.
[**Expanded Voice Support**](#expanded-voice-support)
We now offer an even greater selection of natural-sounding AI voices. We've added support for a variety of new options from ElevenLabs and Rime. Please note that using these voices consumes AI tokens. Check them out for your projects that could benefit from additional voice choices.
## Important Update: Deprecation of AI Response and AI Set Steps
This is an important update to our platform. As part of our ongoing commitment to enhancing your experience and providing the most advanced tools for AI agent development, we have made the decision to deprecate the AI Response and AI Set steps.
What does this mean for you?
- On February 4th, 2025, the AI Response and AI Set steps will be disabled from the step toolbar in the Voiceflow interface to encourage users to move away of these deprecated steps. Existing steps will remain untouched and will continue working as per normal.
- On June 3rd, 2025, these steps will no longer be supported. Any existing projects using these steps will need to be migrated to the new [Prompt](/docs/documentation/build/steps/message) and [Set](/docs/documentation/build/steps/set) steps. We will be sending out additional communication in advance to the sunset date.
We understand that this change may require some adjustments to your workflow, but rest assured that we are here to support you throughout this transition. The new Prompt and Set steps, along with our powerful Prompt CMS, offer even more flexibility and control over your conversational experiences.
Some key benefits of the new approach include:
- Centralized prompt management:[The Prompt CMS](/docs/documentation/build/global-prompt) serves as a hub for all your prompts, making it easy to create, edit, and reuse them across your projects.
- Advanced prompt configuration: Leverage system prompts, message pairs, conversation history, and variables to craft highly contextual and dynamic responses.
- Seamless integration: The Prompt step allows you to bring your prompts directly into your conversation flows, while the Set step lets you assign prompt outputs to variables for enhanced logic and control.
- Continued innovation: We are committed to expanding the capabilities of these new features, with exciting updates planned for the near future.
For those using the Knowledge Base, we recommend transitioning to the[KB Search step](/docs/documentation/build/querying-the-knowledge-base). This step allows you to query your Knowledge Base and feed the results into a prompt, enabling even more intelligent and relevant responses.
To help guide you through migrating from the AI steps to the Prompt step, check our walkthrough below:
We value your feedback and are here to address any questions or concerns you may have. Our team is dedicated to ensuring a smooth transition and helping you unlock the full potential of these powerful new features.
Thank you for your understanding and continued support. We are excited about the future of conversational AI development on Voiceflow and look forward to seeing the incredible experiences you will create with these enhanced capabilities.
Best regards,
Voiceflow
# Authenticate the vf CLI
Source: https://www.voiceflow.com/docs/cli/authentication
Authenticate the vf CLI with the VF_TOKEN environment variable, the token flag, or an interactive login, and check what is configured with vf auth whoami.
The CLI resolves credentials from three sources, in priority order: the global
`--token` flag, the `VF_TOKEN` environment variable, and credentials stored
locally by an interactive login.
## Interactive login
```bash
vf auth login
```
Walks you through configuring credentials interactively. All fields are
optional, press Enter to skip any field you don't need.
## Check who you are
```bash
vf auth whoami
```
Shows which credential source is configured (flag, environment variable,
keychain, or config file), with the token masked. Also available as the
top-level alias `vf whoami`.
`whoami` runs entirely offline. It does not validate the token against the
API, so for a live check run a real command such as `vf workspace list`.
## Sign out
```bash
vf auth logout
```
Clears all stored credentials.
## Non-interactive use (CI and coding agents)
The CLI reads the `VF_TOKEN` environment variable natively, so there is no
login step and nothing stored on disk:
```bash
export VF_TOKEN=vfp_...
vf workspace list --output-format json
```
Every command also accepts the token directly with the global `--token` flag:
```bash
vf workspace list --token "$VF_TOKEN"
```
Store the token as a secret in your CI provider. Never commit it: the token
grants the same access as your account. Full flag reference:
[vf auth](/docs/cli/commands/auth).
# vf agent - Operations for agent
Source: https://www.voiceflow.com/docs/cli/commands/agent
vf agent: operations for agent. Groups 2 subcommands: get, update.
Operations for agent.
## Usage
```bash
vf agent [flags]
```
## Flags
```text
-h, --help help for agent
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
- [vf agent get](/docs/cli/commands/agent/get) - Get agent
- [vf agent update](/docs/cli/commands/agent/update) - Update agent
# vf agent get - Get agent
Source: https://www.voiceflow.com/docs/cli/commands/agent/get
vf agent get: get agent. Requires --environment-alias and --project-id, with a worked example.
Get agent configuration.
## Usage
```bash
vf agent get [flags]
```
## Examples
```bash
vf agent get --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for get
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf agent](/docs/cli/commands/agent) - Operations for agent
# vf agent update - Update agent
Source: https://www.voiceflow.com/docs/cli/commands/agent/update
vf agent update: update agent. Requires --environment-alias and --project-id, with a worked example.
Update agent configuration.
## Usage
```bash
vf agent update [flags]
```
## Examples
```bash
vf agent update --project-id --environment-alias
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-b, --button-tool string JSON object
--call-forward-tool string JSON object
--card-tool string JSON object
--carousel-tool string JSON object
--end-tool string JSON object
--environment-alias string [required]
-h, --help help for update
--include-guidelines Whether to append the default prompting guidelines to the global prompt.
--instructions string list of values
-k, --knowledge-base-tool string JSON object
-l, --llm string JSON object
--path-tool-order stringArray The ordered list of path tool IDs that controls the order of the agent exit paths.
--playbooks string Playbooks available for the agent to invoke.
--project-id string [required]
--prompt string list of values
-s, --skip-turn-tool string JSON object
-v, --voice string JSON object
--web-search-tool string JSON object
--workflows string Workflows available for the agent to invoke.
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf agent](/docs/cli/commands/agent) - Operations for agent
# vf analytics - Operations for analytics
Source: https://www.voiceflow.com/docs/cli/commands/analytics
vf analytics: operations for analytics. Groups 1 subcommand: query.
Operations for analytics.
## Usage
```bash
vf analytics [flags]
```
## Flags
```text
-h, --help help for analytics
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query
vf analytics query: operations for query. Groups 25 subcommands, including api-tool-usage, call-count, call-duration, category-token-usage, daily-token-usage.
Operations for query.
## Usage
```bash
vf analytics query [flags]
```
## Flags
```text
-h, --help help for query
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics](/docs/cli/commands/analytics) - Operations for analytics
- [vf analytics query api-tool-usage](/docs/cli/commands/analytics/query/api-tool-usage) - Query API tool usage
- [vf analytics query call-count](/docs/cli/commands/analytics/query/call-count) - Query call count
- [vf analytics query call-duration](/docs/cli/commands/analytics/query/call-duration) - Query call duration
- [vf analytics query category-token-usage](/docs/cli/commands/analytics/query/category-token-usage) - Query category token usage
- [vf analytics query daily-token-usage](/docs/cli/commands/analytics/query/daily-token-usage) - Query daily token usage
- [vf analytics query entity-token-usage](/docs/cli/commands/analytics/query/entity-token-usage) - Query entity token usage
- [vf analytics query function-usage](/docs/cli/commands/analytics/query/function-usage) - Query function usage
- [vf analytics query hourly-organization-token-usage](/docs/cli/commands/analytics/query/hourly-organization-token-usage) - Query hourly organization token usage
- [vf analytics query hourly-project-token-usage](/docs/cli/commands/analytics/query/hourly-project-token-usage) - Query hourly project token usage
- [vf analytics query integration-usage](/docs/cli/commands/analytics/query/integration-usage) - Query integration usage
- [vf analytics query intent-usage](/docs/cli/commands/analytics/query/intent-usage) - Query intent usage
- [vf analytics query knowledge-base-document-usage](/docs/cli/commands/analytics/query/knowledge-base-document-usage) - Query knowledge base document usage
- [vf analytics query mcp-tool-usage](/docs/cli/commands/analytics/query/mcp-tool-usage) - Query MCP tool usage
- [vf analytics query organization-token-usage](/docs/cli/commands/analytics/query/organization-token-usage) - Query organization token usage
- [vf analytics query playbook-usage](/docs/cli/commands/analytics/query/playbook-usage) - Query playbook usage
- [vf analytics query project-interaction-count](/docs/cli/commands/analytics/query/project-interaction-count) - Query project interaction count
- [vf analytics query project-token-usage](/docs/cli/commands/analytics/query/project-token-usage) - Query project token usage
- [vf analytics query project-transcript-cost](/docs/cli/commands/analytics/query/project-transcript-cost) - Query transcript cost
- [vf analytics query project-transcript-count](/docs/cli/commands/analytics/query/project-transcript-count) - Query project transcript count
- [vf analytics query prompt-usage](/docs/cli/commands/analytics/query/prompt-usage) - Query prompt usage
- [vf analytics query unique-user-count](/docs/cli/commands/analytics/query/unique-user-count) - Query unique user count
- [vf analytics query workflow-usage](/docs/cli/commands/analytics/query/workflow-usage) - Query workflow usage
- [vf analytics query workspace-interaction-count](/docs/cli/commands/analytics/query/workspace-interaction-count) - Query workspace interaction count
- [vf analytics query workspace-token-usage](/docs/cli/commands/analytics/query/workspace-token-usage) - Query workspace token usage
- [vf analytics query workspace-transcript-count](/docs/cli/commands/analytics/query/workspace-transcript-count) - Query workspace transcript count
# vf analytics query api-tool-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/api-tool-usage
vf analytics query api-tool-usage: query API tool usage. Requires --end-date, --project-id and --start-date, with a worked example.
Query API tool usage for a project.
## Usage
```bash
vf analytics query api-tool-usage [flags]
```
## Examples
```bash
vf query api-tool-usage --project-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
--exclude-id stringArray list of values
-h, --help help for api-tool-usage
-l, --limit float number value (default 10)
--order-by string options: count, averageLatencyMS
--order-direction string options: ASC, DESC
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query call-count
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/call-count
vf analytics query call-count: query call count. Requires --end-date, --interval, --project-id and --start-date, with a worked example.
Query call count for a project.
## Usage
```bash
vf analytics query call-count [flags]
```
## Examples
```bash
vf query call-count --project-id --end-date --start-date --interval week
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
-h, --help help for call-count
-i, --interval string options: hour, day, week, month [required]
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query call-duration
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/call-duration
vf analytics query call-duration: query call duration. Requires --end-date, --interval, --project-id and --start-date, with a worked example.
Query real call duration (talk time) for a project.
## Usage
```bash
vf analytics query call-duration [flags]
```
## Examples
```bash
vf query call-duration --project-id --end-date --start-date --interval week
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
-h, --help help for call-duration
-i, --interval string options: hour, day, week, month [required]
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query category-token-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/category-token-usage
vf analytics query category-token-usage: query category token usage. Requires --end-date, --interval, --project-id and --start-date, with a worked example.
Query timezone-aware hourly token usage for a project grouped by usage category.
## Usage
```bash
vf analytics query category-token-usage [flags]
```
## Examples
```bash
vf query category-token-usage --project-id --end-date --start-date --interval day
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
-h, --help help for category-token-usage
-i, --interval string options: hour, day, week, month [required]
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-u, --usage-class string options: Host, Build, Test, Monitor
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query daily-token-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/daily-token-usage
vf analytics query daily-token-usage: query daily token usage. Requires --end-date, --organization-id and --start-date, with a worked example.
Daily breakdown of organization token usage grouped by class and category within a date range.
## Usage
```bash
vf analytics query daily-token-usage [flags]
```
## Examples
```bash
vf query daily-token-usage --organization-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --end-date string [required]
-h, --help help for daily-token-usage
--organization-id string [required]
-p, --project-ids stringArray The IDs of the projects to filter results by. Defaults to all projects in the workspace.
-s, --start-date string [required]
-t, --timezone string string value
-w, --workspace-ids stringArray list of values
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query entity-token-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/entity-token-usage
vf analytics query entity-token-usage: query entity token usage. Requires --end-date, --organization-id and --start-date, with a worked example.
Token totals grouped per project and per workspace for an organization.
## Usage
```bash
vf analytics query entity-token-usage [flags]
```
## Examples
```bash
vf query entity-token-usage --organization-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --end-date string [required]
-h, --help help for entity-token-usage
--organization-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query function-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/function-usage
vf analytics query function-usage: query function usage. Requires --end-date, --project-id and --start-date, with a worked example.
Query function usage for a project.
## Usage
```bash
vf analytics query function-usage [flags]
```
## Examples
```bash
vf query function-usage --project-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
--exclude-id stringArray list of values
-h, --help help for function-usage
-l, --limit float number value (default 10)
--order-by string options: count, averageLatencyMS
--order-direction string options: ASC, DESC
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query hourly-organization-token-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/hourly-organization-token-usage
vf analytics query hourly-organization-token-usage: query hourly organization token usage. Requires --end-date, --organization-id and --start-date.
Query hourly token usage for an organization with optional workspace/project filters.
## Usage
```bash
vf analytics query hourly-organization-token-usage [flags]
```
## Examples
```bash
vf query hourly-organization-token-usage --organization-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --end-date string [required]
-h, --help help for hourly-organization-token-usage
--organization-id string [required]
-p, --project-ids stringArray The IDs of the projects to filter results by. Defaults to all projects in the workspace.
-s, --start-date string [required]
-t, --timezone string string value
-w, --workspace-ids stringArray list of values
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query hourly-project-token-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/hourly-project-token-usage
vf analytics query hourly-project-token-usage: query hourly project token usage. Requires --end-date, --interval, --project-id and --start-date.
Query timezone-aware hourly token usage for a project.
## Usage
```bash
vf analytics query hourly-project-token-usage [flags]
```
## Examples
```bash
vf query hourly-project-token-usage --project-id --end-date --start-date --interval hour
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
-h, --help help for hourly-project-token-usage
-i, --interval string options: hour, day, week, month [required]
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-u, --usage-class string options: Host, Build, Test, Monitor
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query integration-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/integration-usage
vf analytics query integration-usage: query integration usage. Requires --end-date, --project-id and --start-date, with a worked example.
Query integration usage for a project.
## Usage
```bash
vf analytics query integration-usage [flags]
```
## Examples
```bash
vf query integration-usage --project-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
--exclude-id stringArray list of values
-h, --help help for integration-usage
-l, --limit float number value (default 10)
--order-by string options: count, averageLatencyMS
--order-direction string options: ASC, DESC
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query intent-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/intent-usage
vf analytics query intent-usage: query intent usage. Requires --end-date, --project-id and --start-date, with a worked example.
Query intent usage for a project.
## Usage
```bash
vf analytics query intent-usage [flags]
```
## Examples
```bash
vf query intent-usage --project-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
--exclude-id stringArray list of values
-h, --help help for intent-usage
-l, --limit float number value (default 10)
--order-direction string options: ASC, DESC
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query knowledge-base-document-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/knowledge-base-document-usage
vf analytics query knowledge-base-document-usage: query knowledge base document usage. Requires --end-date, --project-id and --start-date.
Query knowledge base document usage for a project.
## Usage
```bash
vf analytics query knowledge-base-document-usage [flags]
```
## Examples
```bash
vf query knowledge-base-document-usage --project-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
--exclude-id stringArray list of values
-h, --help help for knowledge-base-document-usage
-l, --limit float number value (default 10)
--order-direction string options: ASC, DESC
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query mcp-tool-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/mcp-tool-usage
vf analytics query mcp-tool-usage: query MCP tool usage. Requires --end-date, --project-id and --start-date, with a worked example.
Query MCP tool usage for a project.
## Usage
```bash
vf analytics query mcp-tool-usage [flags]
```
## Examples
```bash
vf query mcp-tool-usage --project-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
--exclude-id stringArray list of values
-h, --help help for mcp-tool-usage
-l, --limit float number value (default 10)
--order-by string options: count, averageLatencyMS
--order-direction string options: ASC, DESC
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query organization-token-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/organization-token-usage
vf analytics query organization-token-usage: query organization token usage. Requires --end-date, --organization-id and --start-date, with a worked example.
Query token usage for an organization.
## Usage
```bash
vf analytics query organization-token-usage [flags]
```
## Examples
```bash
vf query organization-token-usage --organization-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --end-date string [required]
-h, --help help for organization-token-usage
--organization-id string [required]
-p, --project-ids stringArray The IDs of the projects to filter results by. Defaults to all projects in the workspace.
-s, --start-date string [required]
-t, --timezone string string value
-w, --workspace-ids stringArray list of values
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query playbook-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/playbook-usage
vf analytics query playbook-usage: query playbook usage. Requires --end-date, --project-id and --start-date, with a worked example.
Query playbook usage for a project.
## Usage
```bash
vf analytics query playbook-usage [flags]
```
## Examples
```bash
vf query playbook-usage --project-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
--exclude-id stringArray list of values
-h, --help help for playbook-usage
-l, --limit float number value (default 10)
--order-by string options: count, averageLatencyMS
--order-direction string options: ASC, DESC
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query project-interaction-count
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/project-interaction-count
vf analytics query project-interaction-count: query project interaction count. Requires --end-date, --interval, --project-id and --start-date.
Query interaction count for a project.
## Usage
```bash
vf analytics query project-interaction-count [flags]
```
## Examples
```bash
vf query project-interaction-count --project-id --end-date --start-date --interval week
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
-h, --help help for project-interaction-count
-i, --interval string options: hour, day, week, month [required]
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query project-token-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/project-token-usage
vf analytics query project-token-usage: query project token usage. Requires --end-date, --interval, --project-id and --start-date, with a worked example.
Query token usage for a project.
## Usage
```bash
vf analytics query project-token-usage [flags]
```
## Examples
```bash
vf query project-token-usage --project-id --end-date --start-date --interval hour
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
-h, --help help for project-token-usage
-i, --interval string options: hour, day, week, month [required]
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query project-transcript-cost
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/project-transcript-cost
vf analytics query project-transcript-cost: query transcript cost. Requires --end-date, --interval, --project-id and --start-date, with a worked example.
Query per-interval cost and transcript count for a project.
## Usage
```bash
vf analytics query project-transcript-cost [flags]
```
## Examples
```bash
vf query project-transcript-cost --project-id --end-date --start-date --interval month
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
-h, --help help for project-transcript-cost
-i, --interval string options: hour, day, week, month [required]
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-u, --usage-class string options: Host, Build, Test, Monitor
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query project-transcript-count
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/project-transcript-count
vf analytics query project-transcript-count: query project transcript count. Requires --end-date, --interval, --project-id and --start-date.
Query transcript count for a project.
## Usage
```bash
vf analytics query project-transcript-count [flags]
```
## Examples
```bash
vf query project-transcript-count --project-id --end-date --start-date --interval hour
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
-h, --help help for project-transcript-count
-i, --interval string options: hour, day, week, month [required]
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query prompt-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/prompt-usage
vf analytics query prompt-usage: query prompt usage. Requires --end-date, --project-id and --start-date, with a worked example.
Query prompt usage for a project.
## Usage
```bash
vf analytics query prompt-usage [flags]
```
## Examples
```bash
vf query prompt-usage --project-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
--exclude-id stringArray list of values
-h, --help help for prompt-usage
-l, --limit float number value (default 10)
--order-by string options: count, averageLatencyMS
--order-direction string options: ASC, DESC
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query unique-user-count
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/unique-user-count
vf analytics query unique-user-count: query unique user count. Requires --end-date, --interval, --project-id and --start-date, with a worked example.
Query unique users for a project.
## Usage
```bash
vf analytics query unique-user-count [flags]
```
## Examples
```bash
vf query unique-user-count --project-id --end-date --start-date --interval hour
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
-h, --help help for unique-user-count
-i, --interval string options: hour, day, week, month [required]
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query workflow-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/workflow-usage
vf analytics query workflow-usage: query workflow usage. Requires --end-date, --project-id and --start-date, with a worked example.
Query workflow usage for a project.
## Usage
```bash
vf analytics query workflow-usage [flags]
```
## Examples
```bash
vf query workflow-usage --project-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--end-date string [required]
--environment-alias string The ID or alias of the environment to filter results by. Defaults to all environments.
--exclude-id stringArray list of values
-h, --help help for workflow-usage
-l, --limit float number value (default 10)
--order-direction string options: ASC, DESC
-p, --project-id string [required]
-s, --start-date string [required]
-t, --timezone string string value
-v, --version-param string Filters results to the draft or published version of the environment. Defaults to both. (options: draft, published)
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query workspace-interaction-count
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/workspace-interaction-count
vf analytics query workspace-interaction-count: query workspace interaction count. Requires --end-date, --start-date and --workspace-id, with a worked example.
Query interaction count for a workspace.
## Usage
```bash
vf analytics query workspace-interaction-count [flags]
```
## Examples
```bash
vf query workspace-interaction-count --workspace-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --end-date string [required]
-h, --help help for workspace-interaction-count
-p, --project-ids stringArray The IDs of the projects to filter results by. Defaults to all projects in the workspace.
-s, --start-date string [required]
-t, --timezone string string value
-w, --workspace-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query workspace-token-usage
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/workspace-token-usage
vf analytics query workspace-token-usage: query workspace token usage. Requires --end-date, --start-date and --workspace-id, with a worked example.
Query token usage for a workspace.
## Usage
```bash
vf analytics query workspace-token-usage [flags]
```
## Examples
```bash
vf query workspace-token-usage --workspace-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --end-date string [required]
-h, --help help for workspace-token-usage
-p, --project-ids stringArray The IDs of the projects to filter results by. Defaults to all projects in the workspace.
-s, --start-date string [required]
-t, --timezone string string value
-w, --workspace-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf analytics query workspace-transcript-count
Source: https://www.voiceflow.com/docs/cli/commands/analytics/query/workspace-transcript-count
vf analytics query workspace-transcript-count: query workspace transcript count. Requires --end-date, --start-date and --workspace-id, with a worked example.
Query transcript count for a workspace.
## Usage
```bash
vf analytics query workspace-transcript-count [flags]
```
## Examples
```bash
vf query workspace-transcript-count --workspace-id --end-date --start-date
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --end-date string [required]
-h, --help help for workspace-transcript-count
-p, --project-ids stringArray The IDs of the projects to filter results by. Defaults to all projects in the workspace.
-s, --start-date string [required]
-t, --timezone string string value
-w, --workspace-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf analytics query](/docs/cli/commands/analytics/query) - Operations for query
# vf api-tool - Operations for api-tool
Source: https://www.voiceflow.com/docs/cli/commands/api-tool
vf api-tool: operations for api-tool. Groups 6 subcommands: create, delete, get, list, update, variable.
Operations for api-tool.
## Usage
```bash
vf api-tool [flags]
```
## Flags
```text
-h, --help help for api-tool
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
- [vf api-tool create](/docs/cli/commands/api-tool/create) - Create API tool
- [vf api-tool delete](/docs/cli/commands/api-tool/delete) - Delete API tool
- [vf api-tool get](/docs/cli/commands/api-tool/get) - Get API tool
- [vf api-tool list](/docs/cli/commands/api-tool/list) - List API tools
- [vf api-tool update](/docs/cli/commands/api-tool/update) - Update API tool
- [vf api-tool variable](/docs/cli/commands/api-tool/variable) - Operations for api-tool-variable
# vf api-tool create - Create API tool
Source: https://www.voiceflow.com/docs/cli/commands/api-tool/create
vf api-tool create: create API tool. Requires --environment-alias, --http-method, --name and --project-id, with a worked example.
Create a new API tool.
## Usage
```bash
vf api-tool create [flags]
```
## Examples
```bash
vf api-tool create --project-id --environment-alias --name --http-method put
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-b, --body-param string JSON value (variants: raw-input: { type: string, contentType: string, content: value[] }, form-data: { type: string, formData: object[] }, url-encoded: { type: string, params: object[] })
--body-param.form-data string StableAPIToolCreateRequest_APIToolFormDataBody variant as JSON
--body-param.raw-input string StableAPIToolCreateRequest_APIToolRawBody variant as JSON
--body-param.url-encoded string StableAPIToolCreateRequest_APIToolURLEncodedBody variant as JSON
--description string A description of what the API tool does, used by the agent to decide when to call it.
-e, --environment-alias string [required]
--headers string list of values
-h, --help help for create
--http-method string options: get, put, post, patch, delete [required]
-n, --name string [required]
-p, --project-id string [required]
--query-parameters string list of values
-s, --settings string JSON object
-u, --url string list of values
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf api-tool](/docs/cli/commands/api-tool) - Operations for api-tool
# vf api-tool delete - Delete API tool
Source: https://www.voiceflow.com/docs/cli/commands/api-tool/delete
vf api-tool delete: delete API tool. Requires --environment-alias, --project-id and --tool-id, with a worked example.
Delete an API tool by ID.
## Usage
```bash
vf api-tool delete [flags]
```
## Examples
```bash
vf api-tool delete --tool-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for delete
-p, --project-id string [required]
-t, --tool-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf api-tool](/docs/cli/commands/api-tool) - Operations for api-tool
# vf api-tool get - Get API tool
Source: https://www.voiceflow.com/docs/cli/commands/api-tool/get
vf api-tool get: get API tool. Requires --environment-alias, --project-id and --tool-id, with a worked example.
Get an API tool by ID.
## Usage
```bash
vf api-tool get [flags]
```
## Examples
```bash
vf api-tool get --tool-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for get
-p, --project-id string [required]
-t, --tool-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf api-tool](/docs/cli/commands/api-tool) - Operations for api-tool
# vf api-tool list - List API tools
Source: https://www.voiceflow.com/docs/cli/commands/api-tool/list
vf api-tool list: list API tools. Requires --environment-alias and --project-id, with a worked example.
List all API tools by project ID.
## Usage
```bash
vf api-tool list [flags]
```
## Examples
```bash
vf api-tool list --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for list
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf api-tool](/docs/cli/commands/api-tool) - Operations for api-tool
# vf api-tool update - Update API tool
Source: https://www.voiceflow.com/docs/cli/commands/api-tool/update
vf api-tool update: update API tool. Requires --environment-alias, --project-id and --tool-id, with a worked example.
Update an API tool by ID.
## Usage
```bash
vf api-tool update [flags]
```
## Examples
```bash
vf api-tool update --tool-id --project-id --environment-alias
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-b, --body-param string JSON value (variants: raw-input: { type: string, contentType: string, content: value[] }, form-data: { type: string, formData: object[] }, url-encoded: { type: string, params: object[] })
--body-param.form-data string StableAPIToolUpdateRequest_APIToolFormDataBody variant as JSON
--body-param.raw-input string StableAPIToolUpdateRequest_APIToolRawBody variant as JSON
--body-param.url-encoded string StableAPIToolUpdateRequest_APIToolURLEncodedBody variant as JSON
--description string A description of what the API tool does, used by the agent to decide when to call it.
-e, --environment-alias string [required]
--headers string list of values
-h, --help help for update
--http-method string options: get, put, post, patch, delete
-n, --name string string value
-p, --project-id string [required]
--query-parameters string list of values
-s, --settings string JSON object
-t, --tool-id string [required]
-u, --url string list of values
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf api-tool](/docs/cli/commands/api-tool) - Operations for api-tool
# vf api-tool variable
Source: https://www.voiceflow.com/docs/cli/commands/api-tool/variable
vf api-tool variable: operations for api-tool-variable. Groups 5 subcommands: create, delete, get, list, update.
Operations for api-tool-variable.
## Usage
```bash
vf api-tool variable [flags]
```
## Flags
```text
-h, --help help for variable
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf api-tool](/docs/cli/commands/api-tool) - Operations for api-tool
- [vf api-tool variable create](/docs/cli/commands/api-tool/variable/create) - Create variable
- [vf api-tool variable delete](/docs/cli/commands/api-tool/variable/delete) - Delete variable
- [vf api-tool variable get](/docs/cli/commands/api-tool/variable/get) - Get variable
- [vf api-tool variable list](/docs/cli/commands/api-tool/variable/list) - List variables
- [vf api-tool variable update](/docs/cli/commands/api-tool/variable/update) - Update variable
# vf api-tool variable create
Source: https://www.voiceflow.com/docs/cli/commands/api-tool/variable/create
vf api-tool variable create: create variable. Requires --api-tool-id, --environment-alias, --name and --project-id, with a worked example.
Create a new variable.
## Usage
```bash
vf api-tool variable create [flags]
```
## Examples
```bash
vf api-tool-variable create --project-id --environment-alias --name --api-tool-id
```
## Flags
```text
-a, --api-tool-id string The ID of the API tool this variable belongs to. [required]
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--description string A description of the variable, used by the agent to determine what value to provide.
-e, --environment-alias string [required]
-h, --help help for create
-n, --name string The name of the variable, referenced within the API tool request. [required]
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf api-tool variable](/docs/cli/commands/api-tool/variable) - Operations for api-tool-variable
# vf api-tool variable delete
Source: https://www.voiceflow.com/docs/cli/commands/api-tool/variable/delete
vf api-tool variable delete: delete variable. Requires --environment-alias, --project-id and --variable-id, with a worked example.
Delete an variable by ID.
## Usage
```bash
vf api-tool variable delete [flags]
```
## Examples
```bash
vf api-tool-variable delete --variable-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for delete
-p, --project-id string [required]
-v, --variable-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf api-tool variable](/docs/cli/commands/api-tool/variable) - Operations for api-tool-variable
# vf api-tool variable get - Get variable
Source: https://www.voiceflow.com/docs/cli/commands/api-tool/variable/get
vf api-tool variable get: get variable. Requires --environment-alias, --project-id and --variable-id, with a worked example.
Get an variable by ID.
## Usage
```bash
vf api-tool variable get [flags]
```
## Examples
```bash
vf api-tool-variable get --variable-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for get
-p, --project-id string [required]
-v, --variable-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf api-tool variable](/docs/cli/commands/api-tool/variable) - Operations for api-tool-variable
# vf api-tool variable list - List variables
Source: https://www.voiceflow.com/docs/cli/commands/api-tool/variable/list
vf api-tool variable list: list variables. Requires --api-tool-id, --environment-alias and --project-id, with a worked example.
List all variables by API tool ID.
## Usage
```bash
vf api-tool variable list [flags]
```
## Examples
```bash
vf api-tool-variable list --project-id --environment-alias --api-tool-id
```
## Flags
```text
-a, --api-tool-id string [required]
-e, --environment-alias string [required]
-h, --help help for list
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf api-tool variable](/docs/cli/commands/api-tool/variable) - Operations for api-tool-variable
# vf api-tool variable update
Source: https://www.voiceflow.com/docs/cli/commands/api-tool/variable/update
vf api-tool variable update: update variable. Requires --environment-alias, --project-id and --variable-id, with a worked example.
Update an variable by ID.
## Usage
```bash
vf api-tool variable update [flags]
```
## Examples
```bash
vf api-tool-variable update --variable-id --project-id --environment-alias
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--description string A description of the variable, used by the agent to determine what value to provide.
-e, --environment-alias string [required]
-h, --help help for update
-n, --name string The name of the variable, referenced within the API tool request.
-p, --project-id string [required]
-v, --variable-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf api-tool variable](/docs/cli/commands/api-tool/variable) - Operations for api-tool-variable
# vf auth
Source: https://www.voiceflow.com/docs/cli/commands/auth
vf auth: manage authentication credentials. Groups 3 subcommands: login, logout, whoami.
Manage authentication credentials.
## Usage
```bash
```
## Flags
```text
-h, --help help for auth
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
- [vf auth login](/docs/cli/commands/auth/login) - Interactively configure authentication credentials
- [vf auth logout](/docs/cli/commands/auth/logout) - Clear all stored authentication credentials
- [vf auth whoami](/docs/cli/commands/auth/whoami) - Display current authentication configuration
# vf auth login
Source: https://www.voiceflow.com/docs/cli/commands/auth/login
vf auth login: interactively configure authentication credentials. Takes no required flags.
Interactively configure authentication credentials for vf.
Secret credentials are stored in the OS keychain when available,
with a config file fallback.
All fields are optional, press Enter to skip any field you don't need.
Use the configure command for both authentication and global parameters.
## Usage
```bash
vf auth login [flags]
```
## Flags
```text
-h, --help help for login
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf auth](/docs/cli/commands/auth) - Manage authentication credentials
# vf auth logout
Source: https://www.voiceflow.com/docs/cli/commands/auth/logout
vf auth logout: clear all stored authentication credentials. Takes no required flags.
Clear all stored authentication credentials from both the OS keychain and config file.
This removes all credentials previously set via auth login or configure.
## Usage
```bash
vf auth logout [flags]
```
## Flags
```text
-h, --help help for logout
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf auth](/docs/cli/commands/auth) - Manage authentication credentials
# vf auth whoami
Source: https://www.voiceflow.com/docs/cli/commands/auth/whoami
vf auth whoami: display current authentication configuration. Takes no required flags.
Display the currently configured settings and their sources.
Sources are shown as:
[flag] - Set via command line flag
[env] - Set via environment variable (VF_*)
[keyring] - Set via OS keychain (stored by login/configure command)
[config] - Set via config file (~/.config/vf/config.yaml)
[unset] - Not configured
Credential values are masked for security.
## Usage
```bash
vf auth whoami [flags]
```
## Flags
```text
-h, --help help for whoami
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf auth](/docs/cli/commands/auth) - Manage authentication credentials
# vf configure
Source: https://www.voiceflow.com/docs/cli/commands/configure
vf configure: configure authentication credentials and preferences. Takes no required flags.
Interactively configure authentication credentials and preferences for the CLI.
Settings are stored in ~/.config/vf/config.yaml.
Secret credentials are stored in the OS keychain when available.
You can also set values via environment variables with the VF_ prefix
(eg: VF_API_KEY) or pass them as flags to individual commands.
Priority: CLI flags > environment variables > OS keychain > config file
## Usage
```bash
vf configure [flags]
```
## Flags
```text
-h, --help help for configure
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
# vf conversation
Source: https://www.voiceflow.com/docs/cli/commands/conversation
vf conversation: operations for conversation. Groups 2 subcommands: send, state.
Operations for conversation.
## Usage
```bash
vf conversation [flags]
```
## Flags
```text
-h, --help help for conversation
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
- [vf conversation send](/docs/cli/commands/conversation/send) - Send
- [vf conversation state](/docs/cli/commands/conversation/state) - Operations for state
# vf conversation send - Send
Source: https://www.voiceflow.com/docs/cli/commands/conversation/send
vf conversation send: send. Requires --environment-alias, --project-id, --user-id and --version-param, with a worked example.
Send message to a conversation.
## Usage
```bash
vf conversation send [flags]
```
## Examples
```bash
vf conversation send --user-id --project-id --environment-alias --action '{"type":"end"}' --version-param draft
```
## Flags
```text
-a, --action string JSON value (one of: { type: string, payload: object, diagramID: string, time: number, ... } | { type: string, payload: string, diagramID: string, time: number, ... } | { type: string, diagramID: string, time: number, metadata: object, ... } | { type: string, payload: value, diagramID: string, time: number, ... })
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --environment-alias string [required]
-h, --help help for send
-p, --project-id string [required]
-s, --session-id string The unique ID of the conversation session to continue.
-u, --user-id string [required]
-v, --version-param string Whether to run the conversation against the draft or published version of the environment. (options: draft, published) [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf conversation](/docs/cli/commands/conversation) - Operations for conversation
# vf conversation state
Source: https://www.voiceflow.com/docs/cli/commands/conversation/state
vf conversation state: operations for state. Groups 4 subcommands: delete, get, update, update-variables.
Operations for state.
## Usage
```bash
vf conversation state [flags]
```
## Flags
```text
-h, --help help for state
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf conversation](/docs/cli/commands/conversation) - Operations for conversation
- [vf conversation state delete](/docs/cli/commands/conversation/state/delete) - Delete state
- [vf conversation state get](/docs/cli/commands/conversation/state/get) - Get state
- [vf conversation state update](/docs/cli/commands/conversation/state/update) - Update state
- [vf conversation state update-variables](/docs/cli/commands/conversation/state/update-variables) - Update variables
# vf conversation state delete
Source: https://www.voiceflow.com/docs/cli/commands/conversation/state/delete
vf conversation state delete: delete state. Requires --environment-alias, --project-id, --user-id and --version-param, with a worked example.
Delete conversation state for a user.
## Usage
```bash
vf conversation state delete [flags]
```
## Examples
```bash
vf state delete --user-id --project-id --environment-alias --version-param draft
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for delete
-p, --project-id string [required]
-u, --user-id string [required]
-v, --version-param string options: draft, published [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf conversation state](/docs/cli/commands/conversation/state) - Operations for state
# vf conversation state get - Get state
Source: https://www.voiceflow.com/docs/cli/commands/conversation/state/get
vf conversation state get: get state. Requires --environment-alias, --project-id, --user-id and --version-param, with a worked example.
Get conversation state for a user.
## Usage
```bash
vf conversation state get [flags]
```
## Examples
```bash
vf state get --user-id --project-id --environment-alias --version-param draft
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for get
-p, --project-id string [required]
-u, --user-id string [required]
-v, --version-param string options: draft, published [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf conversation state](/docs/cli/commands/conversation/state) - Operations for state
# vf conversation state update
Source: https://www.voiceflow.com/docs/cli/commands/conversation/state/update
vf conversation state update: update state. Requires --environment-alias, --project-id, --stack, --storage, --user-id, --variables and --version-param.
Update conversation state for a user.
## Usage
```bash
vf conversation state update [flags]
```
## Examples
```bash
vf state update --user-id --project-id --environment-alias --version-param published --stack '[]'
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --environment-alias string [required]
-h, --help help for update
-p, --project-id string [required]
--stack string The execution stack for the conversation, from root to innermost frame. [required]
--storage string Internal runtime storage persisted across turns of the session. [required]
-u, --user-id string [required]
--variables string The current values of the agent variables for this session. [required]
--version-param string options: draft, published [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf conversation state](/docs/cli/commands/conversation/state) - Operations for state
# vf conversation state update-variables
Source: https://www.voiceflow.com/docs/cli/commands/conversation/state/update-variables
vf conversation state update-variables: update variables. Requires --environment-alias, --project-id, --user-id, --variables and --version-param.
Updates variables in the conversation state by merging with the properties in the request body.
## Usage
```bash
vf conversation state update-variables [flags]
```
## Examples
```bash
vf state update-variables --user-id --project-id --environment-alias --version-param published --variables '{"key":"","key1":"","key2":""}'
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --environment-alias string [required]
-h, --help help for update-variables
-p, --project-id string [required]
-u, --user-id string [required]
--variables string Variable values to set on the conversation session, keyed by variable name. [required]
--version-param string options: draft, published [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf conversation state](/docs/cli/commands/conversation/state) - Operations for state
# vf document
Source: https://www.voiceflow.com/docs/cli/commands/document
vf document: operations for document. Groups 7 subcommands: create-table, create-text, create-url, delete, get, list, update.
Operations for document.
## Usage
```bash
vf document [flags]
```
## Flags
```text
-h, --help help for document
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
- [vf document create-table](/docs/cli/commands/document/create-table) - Create table document
- [vf document create-text](/docs/cli/commands/document/create-text) - Create text document
- [vf document create-url](/docs/cli/commands/document/create-url) - Create URL document
- [vf document delete](/docs/cli/commands/document/delete) - Delete document
- [vf document get](/docs/cli/commands/document/get) - Get document
- [vf document list](/docs/cli/commands/document/list) - List documents
- [vf document update](/docs/cli/commands/document/update) - Update document
# vf document create-table
Source: https://www.voiceflow.com/docs/cli/commands/document/create-table
vf document create-table: create table document. Requires --environment-alias, --items, --name, --project-id and --schema, with a worked example.
Create a new document from structured data.
## Usage
```bash
vf document create-table [flags]
```
## Examples
```bash
vf document create-table --project-id --environment-alias --name --items '[{"key":""},{},{}]' --schema '{"searchableFields":["","",""]}'
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --environment-alias string [required]
-h, --help help for create-table
-i, --items string The table rows to ingest; each row is a flat object and becomes its own chunk. [required]
--llm-based-chunks string JSON value (one of: boolean | StableDocumentController_createTable_llmBasedChunks_enum)
--llm-content-summarization string JSON value (one of: boolean | StableDocumentController_createTable_llmContentSummarization_enum)
--llm-generated-q string JSON value (one of: boolean | StableDocumentController_createTable_llmGeneratedQ_enum)
--llm-prepend-context string JSON value (one of: boolean | StableDocumentController_createTable_llmPrependContext_enum)
--markdown-conversion string JSON value (one of: boolean | StableDocumentController_createTable_markdownConversion_enum)
--max-chunk-size string JSON value (one of: string | number)
--metadata string Properties that can be filtered on at runtime (static or dynamic from a variable). Put your most common filter dimensions here.
-n, --name string [required]
--overwrite string JSON value (one of: boolean | StableDocumentController_createTable_overwrite_enum)
-p, --project-id string [required]
-s, --schema string Declares which top-level keys of each row are full-text searchable versus row-level metadata. [required]
-u, --url string An optional source URL to associate with the table document.
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf document](/docs/cli/commands/document) - Operations for document
# vf document create-text
Source: https://www.voiceflow.com/docs/cli/commands/document/create-text
vf document create-text: create text document. Requires --environment-alias, --file and --project-id, with a worked example.
Create a new document from raw text.
## Usage
```bash
vf document create-text [flags]
```
## Examples
```bash
vf document create-text --project-id --environment-alias
```
## Flags
```text
-c, --can-edit If true, the document content can be edited in the Creator after upload.
-e, --environment-alias string [required]
-f, --file string Path to file to upload [required]
-h, --help help for create-text
--llm-based-chunks string JSON value (one of: boolean | StableDocumentController_createText_llmBasedChunks_enum)
--llm-content-summarization string JSON value (one of: boolean | StableDocumentController_createText_llmContentSummarization_enum)
--llm-generated-q string JSON value (one of: boolean | StableDocumentController_createText_llmGeneratedQ_enum)
--llm-prepend-context string JSON value (one of: boolean | StableDocumentController_createText_llmPrependContext_enum)
--markdown-conversion string JSON value (one of: boolean | StableDocumentController_createText_markdownConversion_enum)
--max-chunk-size string JSON value (one of: string | number)
--metadata { key, values } A JSON-encoded array of { key, values } metadata tags attached to the document, used to filter knowledge base retrieval at runtime.
--overwrite string JSON value (one of: boolean | StableDocumentController_createText_overwrite_enum)
-p, --project-id string [required]
-u, --url string An optional source URL to associate with the uploaded document.
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf document](/docs/cli/commands/document) - Operations for document
# vf document create-url
Source: https://www.voiceflow.com/docs/cli/commands/document/create-url
vf document create-url: create URL document. Requires --environment-alias, --project-id and --url, with a worked example.
Create a new document from a URL.
## Usage
```bash
vf document create-url [flags]
```
## Examples
```bash
vf document create-url --project-id --environment-alias --url https://deserted-swordfish.info/
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --environment-alias string [required]
-h, --help help for create-url
--llm-based-chunks string JSON value (one of: boolean | StableDocumentController_createURL_llmBasedChunks_enum)
--llm-content-summarization string JSON value (one of: boolean | StableDocumentController_createURL_llmContentSummarization_enum)
--llm-generated-q string JSON value (one of: boolean | StableDocumentController_createURL_llmGeneratedQ_enum)
--llm-prepend-context string JSON value (one of: boolean | StableDocumentController_createURL_llmPrependContext_enum)
--markdown-conversion string JSON value (one of: boolean | StableDocumentController_createURL_markdownConversion_enum)
--max-chunk-size string JSON value (one of: string | number)
--metadata string Metadata tags attached to the document, used to filter knowledge base retrieval at runtime.
--overwrite string JSON value (one of: boolean | StableDocumentController_createURL_overwrite_enum)
-p, --project-id string [required]
-r, --refresh-rate string How often the URL is automatically re-crawled to refresh the document content. (options: daily, weekly, monthly, never)
-u, --url string The URL of the web page to crawl and ingest into the knowledge base. [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf document](/docs/cli/commands/document) - Operations for document
# vf document delete
Source: https://www.voiceflow.com/docs/cli/commands/document/delete
vf document delete: delete document. Requires --document-id, --environment-alias and --project-id, with a worked example.
Delete a document by ID.
## Usage
```bash
vf document delete [flags]
```
## Examples
```bash
vf document delete --document-id --project-id --environment-alias
```
## Flags
```text
--document-id string [required]
-e, --environment-alias string [required]
-h, --help help for delete
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf document](/docs/cli/commands/document) - Operations for document
# vf document get - Get document
Source: https://www.voiceflow.com/docs/cli/commands/document/get
vf document get: get document. Requires --document-id, --environment-alias and --project-id, with a worked example.
Get a document by ID.
## Usage
```bash
vf document get [flags]
```
## Examples
```bash
vf document get --document-id --project-id --environment-alias
```
## Flags
```text
--document-id string [required]
-e, --environment-alias string [required]
-h, --help help for get
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf document](/docs/cli/commands/document) - Operations for document
# vf document list - List documents
Source: https://www.voiceflow.com/docs/cli/commands/document/list
vf document list: list documents. Requires --environment-alias and --project-id, with a worked example.
List all documents by project ID.
## Usage
```bash
vf document list [flags]
```
## Examples
```bash
vf document list --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for list
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf document](/docs/cli/commands/document) - Operations for document
# vf document update
Source: https://www.voiceflow.com/docs/cli/commands/document/update
vf document update: update document. Requires --document-id, --environment-alias, --metadata and --project-id, with a worked example.
Update a document by ID.
## Usage
```bash
vf document update [flags]
```
## Examples
```bash
vf document update --document-id --project-id --environment-alias --metadata '[]'
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--document-id string [required]
-e, --environment-alias string [required]
-h, --help help for update
-m, --metadata string Metadata tags attached to the document, used to filter knowledge base retrieval at runtime. [required]
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf document](/docs/cli/commands/document) - Operations for document
# vf environment
Source: https://www.voiceflow.com/docs/cli/commands/environment
vf environment: operations for environment. Groups 9 subcommands: clone, compile, delete, get, list, merge, publish, update, update-traffic-split.
Operations for environment.
## Usage
```bash
vf environment [flags]
```
## Flags
```text
-h, --help help for environment
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
- [vf environment clone](/docs/cli/commands/environment/clone) - Clone environment
- [vf environment compile](/docs/cli/commands/environment/compile) - Compile environment
- [vf environment delete](/docs/cli/commands/environment/delete) - Delete environment
- [vf environment get](/docs/cli/commands/environment/get) - Get environment
- [vf environment list](/docs/cli/commands/environment/list) - List environments
- [vf environment merge](/docs/cli/commands/environment/merge) - Merge environments
- [vf environment publish](/docs/cli/commands/environment/publish) - Publish environment
- [vf environment update](/docs/cli/commands/environment/update) - Update environment
- [vf environment update-traffic-split](/docs/cli/commands/environment/update-traffic-split) - Update traffic split
# vf environment clone
Source: https://www.voiceflow.com/docs/cli/commands/environment/clone
vf environment clone: clone environment. Requires --alias, --environment-alias, --name and --project-id, with a worked example.
Clone an environment.
## Usage
```bash
vf environment clone [flags]
```
## Examples
```bash
vf environment clone --environment-alias --project-id --name --alias
```
## Flags
```text
-a, --alias string Short URL-safe identifier; cannot be 'main' (reserved). [required]
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --environment-alias string [required]
-h, --help help for clone
-n, --name string The display name of the new environment. [required]
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf environment](/docs/cli/commands/environment) - Operations for environment
# vf environment compile
Source: https://www.voiceflow.com/docs/cli/commands/environment/compile
vf environment compile: compile environment. Requires --environment-alias and --project-id, with a worked example.
Compile an environment.
## Usage
```bash
vf environment compile [flags]
```
## Examples
```bash
vf environment compile --environment-alias --project-id
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for compile
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf environment](/docs/cli/commands/environment) - Operations for environment
# vf environment delete
Source: https://www.voiceflow.com/docs/cli/commands/environment/delete
vf environment delete: delete environment. Requires --environment-alias and --project-id, with a worked example.
Delete an environment by alias or ID.
## Usage
```bash
vf environment delete [flags]
```
## Examples
```bash
vf environment delete --environment-alias --project-id
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for delete
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf environment](/docs/cli/commands/environment) - Operations for environment
# vf environment get - Get environment
Source: https://www.voiceflow.com/docs/cli/commands/environment/get
vf environment get: get environment. Requires --environment-alias and --project-id, with a worked example.
Get an environment by alias or ID.
## Usage
```bash
vf environment get [flags]
```
## Examples
```bash
vf environment get --environment-alias --project-id
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for get
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf environment](/docs/cli/commands/environment) - Operations for environment
# vf environment list
Source: https://www.voiceflow.com/docs/cli/commands/environment/list
vf environment list: list environments. Requires --project-id, with a worked example.
List all environments by project ID.
## Usage
```bash
vf environment list [flags]
```
## Examples
```bash
vf environment list --project-id
```
## Flags
```text
-h, --help help for list
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf environment](/docs/cli/commands/environment) - Operations for environment
# vf environment merge
Source: https://www.voiceflow.com/docs/cli/commands/environment/merge
vf environment merge: merge environments. Requires --project-id, --source-environment-alias and --target-environment-alias, with a worked example.
Merge one environment into another.
## Usage
```bash
vf environment merge [flags]
```
## Examples
```bash
vf environment merge --project-id --source-environment-alias --target-environment-alias
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-h, --help help for merge
-p, --project-id string [required]
-r, --remove-source-environment If true, the source environment is deleted after the merge.
-s, --source-environment-alias string The alias of the environment whose changes are merged. [required]
-t, --target-environment-alias string The alias of the environment that receives the merged changes. [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf environment](/docs/cli/commands/environment) - Operations for environment
# vf environment publish
Source: https://www.voiceflow.com/docs/cli/commands/environment/publish
vf environment publish: publish environment. Requires --environment-alias, --name and --project-id, with a worked example.
Publish live version of an environment.
## Usage
```bash
vf environment publish [flags]
```
## Examples
```bash
vf environment publish --environment-alias --project-id --name
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--description string An optional description of what changed in this release. (default "null")
-e, --environment-alias string [required]
-h, --help help for publish
-n, --name string The name of the release created by publishing. [required]
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf environment](/docs/cli/commands/environment) - Operations for environment
# vf environment update
Source: https://www.voiceflow.com/docs/cli/commands/environment/update
vf environment update: update environment. Requires --environment-alias and --project-id, with a worked example.
Update a environment by alias or ID.
## Usage
```bash
vf environment update [flags]
```
## Examples
```bash
vf environment update --environment-alias --project-id
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --environment-alias string [required]
-h, --help help for update
-n, --name string string value
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf environment](/docs/cli/commands/environment) - Operations for environment
# vf environment update-traffic-split
Source: https://www.voiceflow.com/docs/cli/commands/environment/update-traffic-split
vf environment update-traffic-split: update traffic split. Requires --project-id and --traffic, with a worked example.
Update the percentage of traffic routed to each environment.
## Usage
```bash
vf environment update-traffic-split [flags]
```
## Examples
```bash
vf environment update-traffic-split --project-id --traffic '{"key":1314.98,"key1":2310.29}'
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-h, --help help for update-traffic-split
-p, --project-id string [required]
-t, --traffic string Map of environmentAlias → traffic percentage (0-100). Values must sum to 100. [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf environment](/docs/cli/commands/environment) - Operations for environment
# vf evaluation
Source: https://www.voiceflow.com/docs/cli/commands/evaluation
vf evaluation: operations for evaluation. Groups 6 subcommands: create, delete, get, list, run, update.
Operations for evaluation.
## Usage
```bash
vf evaluation [flags]
```
## Flags
```text
-h, --help help for evaluation
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
- [vf evaluation create](/docs/cli/commands/evaluation/create) - Create evaluation
- [vf evaluation delete](/docs/cli/commands/evaluation/delete) - Delete evaluation
- [vf evaluation get](/docs/cli/commands/evaluation/get) - Get evaluation
- [vf evaluation list](/docs/cli/commands/evaluation/list) - List evaluations
- [vf evaluation run](/docs/cli/commands/evaluation/run) - Run evaluation
- [vf evaluation update](/docs/cli/commands/evaluation/update) - Update evaluation
# vf evaluation create
Source: https://www.voiceflow.com/docs/cli/commands/evaluation/create
vf evaluation create: create evaluation. Requires --body-param and --project-id, with a worked example.
Create a new evaluation.
## Usage
```bash
vf evaluation create [flags]
```
## Examples
```bash
vf evaluation create --project-id
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-b, --body-param string JSON value (variants: boolean: { type: string, truePrompt: string, falsePrompt: string, name: string, ... }, number: { type: string, minimumValue: number, maximumValue: number, minimumPrompt: string, ... }, string: { type: string, name: string, prompt: string, enabled: boolean, ... }, option: { type: string, options: object[], name: string, prompt: string, ... })
--body-param.boolean string StableEvaluationCreateRequest_Boolean variant as JSON
--body-param.boolean.description string A human-readable description of what this evaluation measures.
--body-param.boolean.enabled Whether this evaluation runs automatically against new transcripts. [required]
--body-param.boolean.false-prompt false The criteria describing when the evaluator should return false. [required]
--body-param.boolean.name string [required]
--body-param.boolean.prompt string The criteria the evaluator uses to judge a transcript. [required]
--body-param.boolean.true-prompt true The criteria describing when the evaluator should return true. [required]
--body-param.number string StableEvaluationCreateRequest_Number variant as JSON
--body-param.number.description string A human-readable description of what this evaluation measures.
--body-param.number.enabled Whether this evaluation runs automatically against new transcripts. [required]
--body-param.number.maximum-prompt maximumValue The criteria describing what warrants the maximumValue score. [required]
--body-param.number.maximum-value float The highest score the evaluator can assign. [required]
--body-param.number.minimum-prompt minimumValue The criteria describing what warrants the minimumValue score. [required]
--body-param.number.minimum-value float The lowest score the evaluator can assign. [required]
--body-param.number.name string [required]
--body-param.number.prompt string The criteria the evaluator uses to judge a transcript. [required]
--body-param.option string StableEvaluationCreateRequest_Option_2 variant as JSON
--body-param.string string StableEvaluationCreateRequest_String variant as JSON
--body-param.string.description string A human-readable description of what this evaluation measures.
--body-param.string.enabled Whether this evaluation runs automatically against new transcripts. [required]
--body-param.string.name string [required]
--body-param.string.prompt string The criteria the evaluator uses to judge a transcript. [required]
-h, --help help for create
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf evaluation](/docs/cli/commands/evaluation) - Operations for evaluation
# vf evaluation delete
Source: https://www.voiceflow.com/docs/cli/commands/evaluation/delete
vf evaluation delete: delete evaluation. Requires --evaluation-id and --project-id, with a worked example.
Delete an evaluation by ID.
## Usage
```bash
vf evaluation delete [flags]
```
## Examples
```bash
vf evaluation delete --evaluation-id --project-id
```
## Flags
```text
-e, --evaluation-id string [required]
-h, --help help for delete
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf evaluation](/docs/cli/commands/evaluation) - Operations for evaluation
# vf evaluation get - Get evaluation
Source: https://www.voiceflow.com/docs/cli/commands/evaluation/get
vf evaluation get: get evaluation. Requires --evaluation-id and --project-id, with a worked example.
Get an evaluation by ID.
## Usage
```bash
vf evaluation get [flags]
```
## Examples
```bash
vf evaluation get --evaluation-id --project-id
```
## Flags
```text
-e, --evaluation-id string [required]
-h, --help help for get
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf evaluation](/docs/cli/commands/evaluation) - Operations for evaluation
# vf evaluation list - List evaluations
Source: https://www.voiceflow.com/docs/cli/commands/evaluation/list
vf evaluation list: list evaluations. Requires --project-id, with a worked example.
List all evaluations by project ID.
## Usage
```bash
vf evaluation list [flags]
```
## Examples
```bash
vf evaluation list --project-id
```
## Flags
```text
-h, --help help for list
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf evaluation](/docs/cli/commands/evaluation) - Operations for evaluation
# vf evaluation run - Run evaluation
Source: https://www.voiceflow.com/docs/cli/commands/evaluation/run
vf evaluation run: run evaluation. Requires --evaluation-id, --project-id and --transcript-id, with a worked example.
Run an evaluation.
## Usage
```bash
vf evaluation run [flags]
```
## Examples
```bash
vf evaluation run --evaluation-id --project-id --transcript-id
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --evaluation-id string [required]
-h, --help help for run
-p, --project-id string [required]
-t, --transcript-id string The ID of the transcript to run the evaluation against. [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf evaluation](/docs/cli/commands/evaluation) - Operations for evaluation
# vf evaluation update
Source: https://www.voiceflow.com/docs/cli/commands/evaluation/update
vf evaluation update: update evaluation. Requires --evaluation-id and --project-id, with a worked example.
Update an evaluation by ID.
## Usage
```bash
vf evaluation update [flags]
```
## Examples
```bash
vf evaluation update --evaluation-id --project-id
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-b, --body-param string JSON value (variants: boolean: { truePrompt: string, falsePrompt: string, name: string, prompt: string, ... }, number: { minimumValue: number, maximumValue: number, minimumPrompt: string, maximumPrompt: string, ... }, string: { name: string, prompt: string, enabled: boolean, settings: object, ... }, option: { options: object[], name: string, prompt: string, enabled: boolean, ... })
--body-param.boolean string StableEvaluationUpdateRequest_Boolean variant as JSON
--body-param.number string StableEvaluationUpdateRequest_Number variant as JSON
--body-param.option string StableEvaluationUpdateRequest_Option_2 variant as JSON
--body-param.string string StableEvaluationUpdateRequest_String variant as JSON
-e, --evaluation-id string [required]
-h, --help help for update
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf evaluation](/docs/cli/commands/evaluation) - Operations for evaluation
# vf explore
Source: https://www.voiceflow.com/docs/cli/commands/explore
vf explore: interactively browse and run commands. Takes no required flags.
Launch an interactive command explorer to browse available commands, view their descriptions and flags, and execute them.
## Usage
```bash
vf explore [flags]
```
## Flags
```text
-h, --help help for explore
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
# vf function - Operations for function
Source: https://www.voiceflow.com/docs/cli/commands/function
vf function: operations for function. Groups 7 subcommands: create, delete, get, list, path, update, variable.
Operations for function.
## Usage
```bash
vf function [flags]
```
## Flags
```text
-h, --help help for function
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
- [vf function create](/docs/cli/commands/function/create) - Create function
- [vf function delete](/docs/cli/commands/function/delete) - Delete function
- [vf function get](/docs/cli/commands/function/get) - Get function
- [vf function list](/docs/cli/commands/function/list) - List functions
- [vf function path](/docs/cli/commands/function/path) - Operations for path
- [vf function update](/docs/cli/commands/function/update) - Update function
- [vf function variable](/docs/cli/commands/function/variable) - Operations for function-variable
# vf function create - Create function
Source: https://www.voiceflow.com/docs/cli/commands/function/create
vf function create: create function. Requires --code, --environment-alias, --name and --project-id, with a worked example.
Create a new function.
## Usage
```bash
vf function create [flags]
```
## Examples
```bash
vf function create --project-id --environment-alias --name --code
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-c, --code string The JavaScript source code executed when the function runs. [required]
--description string A human-readable description of what the function does.
-e, --environment-alias string [required]
-h, --help help for create
-n, --name string [required]
-p, --project-id string [required]
-s, --settings string JSON object
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function](/docs/cli/commands/function) - Operations for function
# vf function delete - Delete function
Source: https://www.voiceflow.com/docs/cli/commands/function/delete
vf function delete: delete function. Requires --environment-alias, --function-id and --project-id, with a worked example.
Delete a function by ID.
## Usage
```bash
vf function delete [flags]
```
## Examples
```bash
vf function delete --function-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-f, --function-id string [required]
-h, --help help for delete
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function](/docs/cli/commands/function) - Operations for function
# vf function get - Get function
Source: https://www.voiceflow.com/docs/cli/commands/function/get
vf function get: get function. Requires --environment-alias, --function-id and --project-id, with a worked example.
Get a function by ID.
## Usage
```bash
vf function get [flags]
```
## Examples
```bash
vf function get --function-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-f, --function-id string [required]
-h, --help help for get
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function](/docs/cli/commands/function) - Operations for function
# vf function list - List functions
Source: https://www.voiceflow.com/docs/cli/commands/function/list
vf function list: list functions. Requires --environment-alias and --project-id, with a worked example.
List all functions by project ID.
## Usage
```bash
vf function list [flags]
```
## Examples
```bash
vf function list --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for list
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function](/docs/cli/commands/function) - Operations for function
# vf function path - Operations for path
Source: https://www.voiceflow.com/docs/cli/commands/function/path
vf function path: operations for path. Groups 5 subcommands: create, delete, get, list, update.
Operations for path.
## Usage
```bash
vf function path [flags]
```
## Flags
```text
-h, --help help for path
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function](/docs/cli/commands/function) - Operations for function
- [vf function path create](/docs/cli/commands/function/path/create) - Create path
- [vf function path delete](/docs/cli/commands/function/path/delete) - Delete path
- [vf function path get](/docs/cli/commands/function/path/get) - Get path
- [vf function path list](/docs/cli/commands/function/path/list) - List paths
- [vf function path update](/docs/cli/commands/function/path/update) - Update path
# vf function path create - Create path
Source: https://www.voiceflow.com/docs/cli/commands/function/path/create
vf function path create: create path. Requires --environment-alias, --function-id, --name and --project-id, with a worked example.
Create a new path.
## Usage
```bash
vf function path create [flags]
```
## Examples
```bash
vf path create --project-id --environment-alias --name --function-id
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --environment-alias string [required]
-f, --function-id string The ID of the function this path belongs to. [required]
-h, --help help for create
-l, --label name The display label shown for this path in the Voiceflow UI; falls back to name when null. (default "null")
-n, --name string The name of the exit path, referenced by the function code when returning which path to take. [required]
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function path](/docs/cli/commands/function/path) - Operations for path
# vf function path delete - Delete path
Source: https://www.voiceflow.com/docs/cli/commands/function/path/delete
vf function path delete: delete path. Requires --environment-alias, --path-id and --project-id, with a worked example.
Delete a path by ID.
## Usage
```bash
vf function path delete [flags]
```
## Examples
```bash
vf path delete --path-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for delete
--path-id string [required]
--project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function path](/docs/cli/commands/function/path) - Operations for path
# vf function path get - Get path
Source: https://www.voiceflow.com/docs/cli/commands/function/path/get
vf function path get: get path. Requires --environment-alias, --path-id and --project-id, with a worked example.
Get a path by ID.
## Usage
```bash
vf function path get [flags]
```
## Examples
```bash
vf path get --path-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for get
--path-id string [required]
--project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function path](/docs/cli/commands/function/path) - Operations for path
# vf function path list - List paths
Source: https://www.voiceflow.com/docs/cli/commands/function/path/list
vf function path list: list paths. Requires --environment-alias, --function-id and --project-id, with a worked example.
List all paths by function ID.
## Usage
```bash
vf function path list [flags]
```
## Examples
```bash
vf path list --project-id --environment-alias --function-id
```
## Flags
```text
-e, --environment-alias string [required]
-f, --function-id string [required]
-h, --help help for list
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function path](/docs/cli/commands/function/path) - Operations for path
# vf function path update - Update path
Source: https://www.voiceflow.com/docs/cli/commands/function/path/update
vf function path update: update path. Requires --environment-alias, --path-id and --project-id, with a worked example.
Update a path by ID.
## Usage
```bash
vf function path update [flags]
```
## Examples
```bash
vf path update --path-id --project-id --environment-alias
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-e, --environment-alias string [required]
-h, --help help for update
-l, --label name The display label shown for this path in the Voiceflow UI; falls back to name when null.
-n, --name string The name of the exit path, referenced by the function code when returning which path to take.
--path-id string [required]
--project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function path](/docs/cli/commands/function/path) - Operations for path
# vf function update - Update function
Source: https://www.voiceflow.com/docs/cli/commands/function/update
vf function update: update function. Requires --environment-alias, --function-id and --project-id, with a worked example.
Update a function by ID.
## Usage
```bash
vf function update [flags]
```
## Examples
```bash
vf function update --function-id --project-id --environment-alias
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-c, --code string The JavaScript source code executed when the function runs.
--description string A human-readable description of what the function does.
-e, --environment-alias string [required]
-f, --function-id string [required]
-h, --help help for update
-n, --name string string value
--path-order stringArray An ordered list of path IDs controlling the display order of the function's exit paths.
--project-id string [required]
-s, --settings string JSON object
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function](/docs/cli/commands/function) - Operations for function
# vf function variable
Source: https://www.voiceflow.com/docs/cli/commands/function/variable
vf function variable: operations for function-variable. Groups 5 subcommands: create, delete, get, list, update.
Operations for function-variable.
## Usage
```bash
vf function variable [flags]
```
## Flags
```text
-h, --help help for variable
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function](/docs/cli/commands/function) - Operations for function
- [vf function variable create](/docs/cli/commands/function/variable/create) - Create variable
- [vf function variable delete](/docs/cli/commands/function/variable/delete) - Delete variable
- [vf function variable get](/docs/cli/commands/function/variable/get) - Get variable
- [vf function variable list](/docs/cli/commands/function/variable/list) - List variables
- [vf function variable update](/docs/cli/commands/function/variable/update) - Update variable
# vf function variable create
Source: https://www.voiceflow.com/docs/cli/commands/function/variable/create
vf function variable create: create variable. Requires --environment-alias, --function-id, --name, --project-id and --type, with a worked example.
Create a new variable.
## Usage
```bash
vf function variable create [flags]
```
## Examples
```bash
vf function-variable create --project-id --environment-alias --name --type input --function-id
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--description string A human-readable description of what the variable holds.
-e, --environment-alias string [required]
-f, --function-id string The ID of the function this variable belongs to. [required]
-h, --help help for create
-n, --name string The name used to reference the variable in the function code. [required]
-p, --project-id string [required]
-t, --type string options: input, output [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function variable](/docs/cli/commands/function/variable) - Operations for function-variable
# vf function variable delete
Source: https://www.voiceflow.com/docs/cli/commands/function/variable/delete
vf function variable delete: delete variable. Requires --environment-alias, --project-id and --variable-id, with a worked example.
Delete a variable by ID.
## Usage
```bash
vf function variable delete [flags]
```
## Examples
```bash
vf function-variable delete --variable-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for delete
-p, --project-id string [required]
-v, --variable-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function variable](/docs/cli/commands/function/variable) - Operations for function-variable
# vf function variable get - Get variable
Source: https://www.voiceflow.com/docs/cli/commands/function/variable/get
vf function variable get: get variable. Requires --environment-alias, --project-id and --variable-id, with a worked example.
Get a variable by ID.
## Usage
```bash
vf function variable get [flags]
```
## Examples
```bash
vf function-variable get --variable-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for get
-p, --project-id string [required]
-v, --variable-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function variable](/docs/cli/commands/function/variable) - Operations for function-variable
# vf function variable list - List variables
Source: https://www.voiceflow.com/docs/cli/commands/function/variable/list
vf function variable list: list variables. Requires --environment-alias, --function-id and --project-id, with a worked example.
List all variables by function ID.
## Usage
```bash
vf function variable list [flags]
```
## Examples
```bash
vf function-variable list --project-id --environment-alias --function-id
```
## Flags
```text
-e, --environment-alias string [required]
-f, --function-id string [required]
-h, --help help for list
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function variable](/docs/cli/commands/function/variable) - Operations for function-variable
# vf function variable update
Source: https://www.voiceflow.com/docs/cli/commands/function/variable/update
vf function variable update: update variable. Requires --environment-alias, --project-id and --variable-id, with a worked example.
Update a variable by ID.
## Usage
```bash
vf function variable update [flags]
```
## Examples
```bash
vf function-variable update --variable-id --project-id --environment-alias
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--description string A human-readable description of what the variable holds.
-e, --environment-alias string [required]
-h, --help help for update
-n, --name string The name used to reference the variable in the function code.
-p, --project-id string [required]
-v, --variable-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf function variable](/docs/cli/commands/function/variable) - Operations for function-variable
# vf knowledge-base
Source: https://www.voiceflow.com/docs/cli/commands/knowledge-base
vf knowledge-base: operations for knowledge-base. Groups 1 subcommand: query.
Operations for knowledge-base.
## Usage
```bash
vf knowledge-base [flags]
```
## Flags
```text
-h, --help help for knowledge-base
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
- [vf knowledge-base query](/docs/cli/commands/knowledge-base/query) - Query knowledge base
# vf knowledge-base query
Source: https://www.voiceflow.com/docs/cli/commands/knowledge-base/query
vf knowledge-base query: query knowledge base. Requires --environment-alias, --project-id, --question and --version-param, with a worked example.
Execute a query against documents in the knowledge base.
## Usage
```bash
vf knowledge-base query [flags]
```
## Examples
```bash
vf knowledge-base query --project-id --environment-alias --version-param published --question
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
-c, --chunk-limit int The maximum number of document chunks to retrieve.
-e, --environment-alias string [required]
-f, --filters string Metadata filters used to narrow down which document chunks are searched.
-h, --help help for query
-i, --instruction string An additional instruction applied when synthesizing the answer from the retrieved chunks.
-p, --project-id string [required]
--question string The natural-language question to ask the knowledge base. [required]
--settings string JSON object
--synthesis Whether to synthesize an answer from the retrieved chunks; when false, only raw chunks are returned.
-v, --version-param string Whether to query the draft or the published version of the knowledge base. (options: draft, published) [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf knowledge-base](/docs/cli/commands/knowledge-base) - Operations for knowledge-base
# vf mcp-server
Source: https://www.voiceflow.com/docs/cli/commands/mcp-server
vf mcp-server: operations for mcp-server. Groups 6 subcommands: create, delete, get, list, sync, update.
Operations for mcp-server.
## Usage
```bash
vf mcp-server [flags]
```
## Flags
```text
-h, --help help for mcp-server
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
- [vf mcp-server create](/docs/cli/commands/mcp-server/create) - Create MCP server
- [vf mcp-server delete](/docs/cli/commands/mcp-server/delete) - Delete MCP server
- [vf mcp-server get](/docs/cli/commands/mcp-server/get) - Get MCP server
- [vf mcp-server list](/docs/cli/commands/mcp-server/list) - List MCP servers
- [vf mcp-server sync](/docs/cli/commands/mcp-server/sync) - Sync MCP server
- [vf mcp-server update](/docs/cli/commands/mcp-server/update) - Update MCP server
# vf mcp-server create
Source: https://www.voiceflow.com/docs/cli/commands/mcp-server/create
vf mcp-server create: create MCP server. Requires --environment-alias, --name, --project-id and --url, with a worked example.
Create a new MCP server.
## Usage
```bash
vf mcp-server create [flags]
```
## Examples
```bash
vf mcp-server create --project-id --environment-alias --name --url '[]'
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--description string A human-readable description of what the MCP server provides. (default "null")
-e, --environment-alias string [required]
--headers string list of values
-h, --help help for create
-n, --name string [required]
-p, --project-id string [required]
-s, --specification string options: 2025-03-26, 2025-06-18 (default "2025-06-18")
-u, --url string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf mcp-server](/docs/cli/commands/mcp-server) - Operations for mcp-server
# vf mcp-server delete
Source: https://www.voiceflow.com/docs/cli/commands/mcp-server/delete
vf mcp-server delete: delete MCP server. Requires --environment-alias, --project-id and --server-id, with a worked example.
Delete an MCP server by ID.
## Usage
```bash
vf mcp-server delete [flags]
```
## Examples
```bash
vf mcp-server delete --server-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for delete
-p, --project-id string [required]
-s, --server-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf mcp-server](/docs/cli/commands/mcp-server) - Operations for mcp-server
# vf mcp-server get - Get MCP server
Source: https://www.voiceflow.com/docs/cli/commands/mcp-server/get
vf mcp-server get: get MCP server. Requires --environment-alias, --project-id and --server-id, with a worked example.
Get an MCP server by ID.
## Usage
```bash
vf mcp-server get [flags]
```
## Examples
```bash
vf mcp-server get --server-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for get
-p, --project-id string [required]
-s, --server-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf mcp-server](/docs/cli/commands/mcp-server) - Operations for mcp-server
# vf mcp-server list - List MCP servers
Source: https://www.voiceflow.com/docs/cli/commands/mcp-server/list
vf mcp-server list: list MCP servers. Requires --environment-alias and --project-id, with a worked example.
List all MCP servers by project ID.
## Usage
```bash
vf mcp-server list [flags]
```
## Examples
```bash
vf mcp-server list --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for list
-p, --project-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf mcp-server](/docs/cli/commands/mcp-server) - Operations for mcp-server
# vf mcp-server sync
Source: https://www.voiceflow.com/docs/cli/commands/mcp-server/sync
vf mcp-server sync: sync MCP server. Requires --environment-alias, --project-id and --server-id, with a worked example.
Sync tool changes for an MCP server by ID.
## Usage
```bash
vf mcp-server sync [flags]
```
## Examples
```bash
vf mcp-server sync --server-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for sync
-p, --project-id string [required]
-s, --server-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf mcp-server](/docs/cli/commands/mcp-server) - Operations for mcp-server
# vf mcp-server update
Source: https://www.voiceflow.com/docs/cli/commands/mcp-server/update
vf mcp-server update: update MCP server. Requires --environment-alias, --project-id and --server-id, with a worked example.
Update an MCP server by ID.
## Usage
```bash
vf mcp-server update [flags]
```
## Examples
```bash
vf mcp-server update --server-id --project-id --environment-alias
```
## Flags
```text
--body string Request body as JSON (alternative to individual flags). Can also be provided via stdin.
--description string A human-readable description of what the MCP server provides.
-e, --environment-alias string [required]
--headers string list of values
-h, --help help for update
-n, --name string string value
-p, --project-id string [required]
--server-id string [required]
--specification string options: 2025-03-26, 2025-06-18
-u, --url string list of values
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf mcp-server](/docs/cli/commands/mcp-server) - Operations for mcp-server
# vf mcp-tool - Operations for mcp-tool
Source: https://www.voiceflow.com/docs/cli/commands/mcp-tool
vf mcp-tool: operations for mcp-tool. Groups 2 subcommands: get, list.
Operations for mcp-tool.
## Usage
```bash
vf mcp-tool [flags]
```
## Flags
```text
-h, --help help for mcp-tool
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
- [vf mcp-tool get](/docs/cli/commands/mcp-tool/get) - Get MCP tool
- [vf mcp-tool list](/docs/cli/commands/mcp-tool/list) - List MCP tools
# vf mcp-tool get - Get MCP tool
Source: https://www.voiceflow.com/docs/cli/commands/mcp-tool/get
vf mcp-tool get: get MCP tool. Requires --environment-alias, --project-id and --tool-id, with a worked example.
Get an MCP tool by ID.
## Usage
```bash
vf mcp-tool get [flags]
```
## Examples
```bash
vf mcp-tool get --tool-id --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for get
-p, --project-id string [required]
-t, --tool-id string [required]
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf mcp-tool](/docs/cli/commands/mcp-tool) - Operations for mcp-tool
# vf mcp-tool list - List MCP tools
Source: https://www.voiceflow.com/docs/cli/commands/mcp-tool/list
vf mcp-tool list: list MCP tools. Requires --environment-alias and --project-id, with a worked example.
List all MCP tools by project ID.
## Usage
```bash
vf mcp-tool list [flags]
```
## Examples
```bash
vf mcp-tool list --project-id --environment-alias
```
## Flags
```text
-e, --environment-alias string [required]
-h, --help help for list
-p, --project-id string [required]
-s, --server-id string string value
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf mcp-tool](/docs/cli/commands/mcp-tool) - Operations for mcp-tool
# vf
Source: https://www.voiceflow.com/docs/cli/commands/overview
vf - Realtime: Realtime gateway API service. Groups 22 subcommands, including agent, analytics, api-tool, auth, configure, conversation, document, environment.
Realtime: Realtime gateway API service.
## Usage
```bash
vf [flags]
```
## Flags
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
-h, --help help for vf
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf agent](/docs/cli/commands/agent) - Operations for agent
- [vf analytics](/docs/cli/commands/analytics) - Operations for analytics
- [vf api-tool](/docs/cli/commands/api-tool) - Operations for api-tool
- [vf auth](/docs/cli/commands/auth) - Manage authentication credentials
- [vf configure](/docs/cli/commands/configure) - Configure authentication credentials and preferences
- [vf conversation](/docs/cli/commands/conversation) - Operations for conversation
- [vf document](/docs/cli/commands/document) - Operations for document
- [vf environment](/docs/cli/commands/environment) - Operations for environment
- [vf evaluation](/docs/cli/commands/evaluation) - Operations for evaluation
- [vf explore](/docs/cli/commands/explore) - Interactively browse and run commands
- [vf function](/docs/cli/commands/function) - Operations for function
- [vf knowledge-base](/docs/cli/commands/knowledge-base) - Operations for knowledge-base
- [vf mcp-server](/docs/cli/commands/mcp-server) - Operations for mcp-server
- [vf mcp-tool](/docs/cli/commands/mcp-tool) - Operations for mcp-tool
- [vf playbook](/docs/cli/commands/playbook) - Operations for playbook
- [vf project](/docs/cli/commands/project) - Operations for project
- [vf tool](/docs/cli/commands/tool) - Operations for tool
- [vf transcript](/docs/cli/commands/transcript) - Operations for transcript
- [vf variable](/docs/cli/commands/variable) - Operations for variable
- [vf version](/docs/cli/commands/version) - Print the CLI version
- [vf whoami](/docs/cli/commands/whoami) - Display current authentication configuration
- [vf workspace](/docs/cli/commands/workspace) - Operations for workspace
# vf playbook - Operations for playbook
Source: https://www.voiceflow.com/docs/cli/commands/playbook
vf playbook: operations for playbook. Groups 5 subcommands: create, delete, get, list, update.
Operations for playbook.
## Usage
```bash
vf playbook [flags]
```
## Flags
```text
-h, --help help for playbook
```
## Global flags
These flags are inherited from the parent command and work on every invocation.
```text
--agent-mode Enable structured errors and default TOON output for AI coding agents. Automatically enabled when a known agent environment is detected (CLAUDE_CODE, CURSOR_AGENT, etc.). Use --agent-mode=false to disable.
--color string Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars. (default "auto")
-d, --debug Log request and response diagnostics to stderr
--dry-run Preview the request that would be sent without executing it (output to stderr)
-H, --header stringArray Set a custom HTTP request header (format: "Key: Value"). Can be specified multiple times.
--include-headers Include HTTP response headers in the output
-q, --jq string Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')
--no-interactive Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)
-o, --output-format string Specify the output format. Options: pretty, json, yaml, table, toon. (default "pretty")
--server-url string Override the default server URL
--timeout string HTTP request timeout (e.g., 30s, 5m, 100ms)
--token string Voiceflow bearer token
--usage Print the CLI Usage schema in KDL format
```
## See also
- [vf](/docs/cli/commands/overview) - Realtime: Realtime gateway API service
- [vf playbook create](/docs/cli/commands/playbook/create) - Create playbook
- [vf playbook delete](/docs/cli/commands/playbook/delete) - Delete playbook
- [vf playbook get](/docs/cli/commands/playbook/get) - Get playbook
- [vf playbook list](/docs/cli/commands/playbook/list) - List playbooks
- [vf playbook update](/docs/cli/commands/playbook/update) - Update playbook
# vf playbook create - Create playbook
Source: https://www.voiceflow.com/docs/cli/commands/playbook/create
vf playbook create: create playbook. Requires --environment-alias, --name and --project-id, with a worked example.
Create a new playbook.
## Usage
```bash
vf playbook create [flags]
```
## Examples
```bash
vf playbook create --project-id --environment-alias