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

# Developer surfaces

> Tokens, traces, the CLI and MCP: the vocabulary for driving Voiceflow over HTTP, including the one credential that is not the others.

The vocabulary for driving Voiceflow over HTTP, from the command line and through MCP — including the
one credential that is not the others. One section per term.

## Credentials

### Personal access token

The credential for the REST API, the `vf` CLI and the MCP server. One token, three surfaces. Created
in Settings → Access tokens, shown once, always beginning with `vfp_`, sent as a Bearer token in the
`Authorization` header; it acts as you across every workspace and expires after the lifetime you pick.

**Also asked as:**
- how do I authenticate against the API
- my request comes back 401 unauthorized
- where do I get a key for the CLI
- the start-conversation call returns 401 even with my API key
- what header does the API want the key in

**Related:** [Session key](#session-key) · [Dialog Manager API key](#dialog-manager-api-key) · [CLI](#cli)

**Documented in:** [Authentication › Create a token](/docs/api-reference/authentication#create-a-token) · [Authentication › Send the token](/docs/api-reference/authentication#send-the-token) · [Authentication › Expiry](/docs/api-reference/authentication#expiry) · [CLI authentication › Interactive login](/docs/cli/authentication#interactive-login) · [Authentication › What a token can reach](/docs/api-reference/authentication#what-a-token-can-reach) · [Authentication › Revoke a token](/docs/api-reference/authentication#revoke-a-token)

### Session key

A separate credential, from the start-session endpoint, used **only** by `/v4/interact`. Passing an
API key there returns 401.

**Also asked as:**
- the interact endpoint rejects my token
- what credential does the v4 conversation API want
- the credential for the v4 interact endpoint
- why does interact return 401 with my token

**Related:** [Personal access token](#personal-access-token) · [Conversation turn](#conversation-turn)

**Documented in:** [Stream a response › How it works](/docs/cookbook/stream-a-response#how-it-works) · [Stream a response › When it fails](/docs/cookbook/stream-a-response#when-it-fails)

### Dialog Manager API key

The runtime credential the outbound phone and SMS endpoints take in their `Authorization` header,
found with the endpoint in the project's Phone numbers settings.

**Also asked as:**
- which key starts an outbound call
- the header for the runtime API
- the key for the runtime endpoints
- authorization for outbound calls and texts

**Related:** [Outbound calling](/docs/resources/glossary/deploy#outbound-calling) · [Personal access token](#personal-access-token)

**Documented in:** [Outbound calling › Headers](/docs/documentation/deploy/phone/outbound-calling#headers) · [Outbound SMS › Headers](/docs/documentation/deploy/sms/outbound#headers)

## The REST API

### REST API

The HTTP surface covering an agent's whole lifecycle: build it from parts, run conversations, publish
through environments, and read back what happened. Base URL `https://realtime-api.voiceflow.com/v1/stable/`;
most endpoints take `projectID` and an environment alias as query parameters.

**Also asked as:**
- do everything from code instead of the Studio
- the endpoints for managing agents
- base URL for API calls

**Related:** [Personal access token](#personal-access-token) · [Conversation turn](#conversation-turn) · [CLI](#cli)

**Documented in:** [What the REST API covers](/docs/api-reference/api-overview) · [Quickstart](/docs/api-reference/quickstart) · [Authentication › Target a project and environment](/docs/api-reference/authentication#target-a-project-and-environment)

### Conversation turn

One round trip with the agent over the API: a PUT to the conversation path keyed by `userID`, with an
`action` (`launch` to start, `text` for what the user typed) and a `version` (`published` or
`draft`). There is no session to create; the `userID` in the path is the conversation.

**Also asked as:**
- send a user message to the agent from my backend
- start a conversation over HTTP
- run the draft version from code while testing

**Related:** [Trace](#trace) · [Conversation state](#conversation-state) · [Conversation](/docs/resources/glossary/core-objects#conversation)

**Documented in:** [Running agents › A conversation is a userID](/docs/api-reference/sections/running-agents#a-conversation-is-a-userid) · [Running agents › The two fields that matter](/docs/api-reference/sections/running-agents#the-two-fields-that-matter) · [Run your first conversation turn](/docs/cookbook/first-conversation-turn)

### Trace

One item in an agent's reply: text, a card, a debug note. A turn returns an array of them — a chat
agent's words arrive as `text` traces, a voice agent's as `speak`; buttons, cards, carousels and debug
output each have their own type.

**Also asked as:**
- the pieces of a response the API returns
- why does one turn come back as several objects
- parse the agent's reply

**Related:** [Conversation turn](#conversation-turn) · [Chat widget extensions](/docs/resources/glossary/deploy#chat-widget-extensions)

**Documented in:** [Trace types](/docs/api-reference/trace-types) · [Running agents › Reading the response](/docs/api-reference/sections/running-agents#reading-the-response) · [PII redaction › Trace data](/docs/documentation/build/data/pii-redaction#trace-data)


### Trace types

The `type` values a turn can return: `text` (Message step, playbooks, no-match and no-reply
reprompts), `speak` (voice), `cardV2`, `carousel`, `choice` (buttons), `visual`, `no-reply`,
`audio`, `block`, `call-forward`, `debug` and the rest of the runtime schema, each with its payload
fields.

**Also asked as:**
- what does a choice trace contain
- the payload of a card in the API response
- which trace carries the buttons

**Related:** [Trace](#trace) · [Conversation turn](#conversation-turn)

**Documented in:** [Trace types › text](/docs/api-reference/trace-types#text) · [Trace types › cardV2](/docs/api-reference/trace-types#cardv2) · [Trace types › choice](/docs/api-reference/trace-types#choice) · [Trace types › no-reply](/docs/api-reference/trace-types#no-reply) · [Trace types › Additional trace types](/docs/api-reference/trace-types#additional-trace-types)

### Conversation state

The stored state of a live conversation: where it stands and what its variables hold. Separate from
the transcript, which is the record. The state endpoints inspect it, change a variable
mid-conversation, or delete it to start over without changing the `userID`.

**Also asked as:**
- set a variable from outside during a conversation
- reset a user's conversation without a new ID
- see what the agent currently believes

**Related:** [Conversation turn](#conversation-turn) · [Variable](/docs/resources/glossary/knowledge-and-data#variable) · [Transcript](/docs/resources/glossary/measure#transcript)

**Documented in:** [Running agents › Conversation state](/docs/api-reference/sections/running-agents#conversation-state)

### Webhook

An HTTP callback Voiceflow sends when something happens: session lifecycle events when conversations
and calls start and end, and organization events.

**Also asked as:**
- get notified when a chat finishes
- callback at the end of a call
- push conversation events to our system
- receive an event when a chat wraps up
- a callback when a session finishes

**Related:** [Events](/docs/resources/glossary/build#events) · [REST API](#rest-api)

**Documented in:** [Session lifecycle webhooks › Session events](/docs/api-reference/webhooks/session-lifecycle#session-events) · [Session lifecycle webhooks › Call events](/docs/api-reference/webhooks/session-lifecycle#call-events) · [What the REST API covers › Webhooks](/docs/api-reference/api-overview#webhooks) · [Organization events](/docs/api-reference/webhooks/org-events)

## The CLI

### CLI

`vf`, the command-line client. Generated from the same OpenAPI spec as the REST API: one command per
endpoint, grouped by resource (`vf agent`, `vf environment`, `vf document`…), with global flags for
JSON output and dry runs.

**Also asked as:**
- manage agents from the terminal
- script a deploy from CI
- the command-line tool for Voiceflow
- install a specific version of the CLI
- pin the vf version in CI
- the install script for macOS, Linux or Windows

**Related:** [Personal access token](#personal-access-token) · [REST API](#rest-api) · [Environment merge (CLI)](#environment-merge-cli)

**Documented in:** [CLI overview](/docs/cli/overview) · [Installing the CLI](/docs/cli/install) · [CLI authentication › Non-interactive use](/docs/cli/authentication#non-interactive-use-ci-and-coding-agents) · [Installing the CLI](/docs/cli/install) · [CLI authentication › Sign out](/docs/cli/authentication#sign-out) · [CLI authentication › Check who you are](/docs/cli/authentication#check-who-you-are)

### Environment merge (CLI)

`vf environment merge`: merges an environment into another from the terminal; the
`--remove-source-environment` flag deletes the source once the merge is done.

**Also asked as:**
- merge from the command line and clean up the branch
- delete the source environment after merging
- merge and delete the source environment from the command line

**Related:** [Merging](/docs/resources/glossary/deploy#merging) · [CLI](#cli)

**Documented in:** [vf environment merge](/docs/cli/commands/environment/merge)

## MCP

### Voiceflow MCP server

The hosted Model Context Protocol server at `https://mcp.voiceflow.com/mcp` that connects AI clients
such as Claude Code, Cursor, Codex and VS Code to your Voiceflow account. It authenticates with
OAuth — you sign in once and the assistant acts on the projects your account can reach.

**Also asked as:**
- let Claude or Cursor edit my agents
- connect an AI coding assistant to my Voiceflow account
- log out of the MCP connection

**Related:** [MCP](/docs/resources/glossary/ai-terms#mcp) · [MCP server](#mcp-server) · [Personal access token](#personal-access-token)

**Documented in:** [Voiceflow MCP overview](/docs/mcp/overview) · [Set up the Voiceflow MCP server](/docs/mcp/claude-code#set-up-the-voiceflow-mcp-server) · [MCP authentication › Signing out](/docs/mcp/authentication#signing-out)

### MCP server

A Model Context Protocol server whose tools an agent can call. Its tools are populated by syncing the
server, not created by hand. This is a server you connect *to* your agent as a tool source — not the
Voiceflow MCP server above, which is the reverse direction.

**Also asked as:**
- connect an external tool server to the assistant
- add tools from a third-party MCP server
- can the agent use a server running on my own machine

**Related:** [MCP tool](#mcp-tool) · [Voiceflow MCP server](#voiceflow-mcp-server) · [Tool](/docs/resources/glossary/build#tool)

**Documented in:** [MCP tool › Creating an MCP tool](/docs/documentation/build/tools/mcp-tool#creating-an-mcp-tool)

### MCP tool

A tool an MCP server advertises. Populated by syncing the server rather than created by hand, so the
list mirrors what the server exposes. Used in a playbook (the agent decides when) or in a workflow
through the MCP step.

**Also asked as:**
- give the assistant a tool from an MCP server
- the agent should call a tool exposed over MCP
- a tool that comes from an MCP server
- sync tools from a server into the agent

**Related:** [MCP server](#mcp-server) · [MCP step](/docs/resources/glossary/build#mcp-step)

**Documented in:** [MCP tool › Using the MCP tool](/docs/documentation/build/tools/mcp-tool#using-the-mcp-tool) · [MCP tool › In a playbook](/docs/documentation/build/tools/mcp-tool#in-a-playbook) · [MCP tool › In a workflow](/docs/documentation/build/tools/mcp-tool#in-a-workflow)