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 · Dialog Manager API key · CLI

Documented in: Authentication › Create a token · Authentication › Send the token · Authentication › Expiry · CLI authentication › Interactive login · Authentication › What a token can reach · 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 · Conversation turn

Documented in: Stream a response › How it works · 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 · Personal access token

Documented in: Outbound calling › Headers · Outbound SMS › 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 · Conversation turn · CLI

Documented in: What the REST API covers · Quickstart · 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 · Conversation state · Conversation

Documented in: Running agents › A conversation is a userID · Running agents › The two fields that matter · Run your 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 · Chat widget extensions

Documented in: Trace types · Running agents › Reading the response · 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 · Conversation turn

Documented in: Trace types › text · Trace types › cardV2 · Trace types › choice · Trace types › no-reply · 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 · Variable · Transcript

Documented in: 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 · REST API

Documented in: Session lifecycle webhooks › Session events · Session lifecycle webhooks › Call events · What the REST API covers › Webhooks · Organization 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

Documented in: CLI overview · Installing the CLI · CLI authentication › Non-interactive use · Installing the CLI · CLI authentication › Sign out · 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 · CLI

Documented in: vf 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 · MCP server · Personal access token

Documented in: Voiceflow MCP overview · Set up the Voiceflow MCP server · 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 · Voiceflow MCP server · Tool

Documented in: 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 step

Documented in: MCP tool › Using the MCP tool · MCP tool › In a playbook · MCP tool › In a workflow