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	Get agent configuration.
PATCH Update agent	Update agent configuration.
GET Read agent instructions	Read a page of the main agent’s routing instructions as numbered lines.
PATCH Patch agent instructions	Replace an exact string in the main agent’s instructions.
POST Search agent instructions	Search the main agent’s instructions with a regular expression.
GET Read the global prompt	Read a page of the global prompt as numbered lines.
PATCH Patch the global prompt	Replace an exact string in the global prompt.
POST Search the global prompt	Search the global prompt with a regular expression.

Playbook

Endpoint	Description
GET List playbooks	List all playbooks by project ID.
POST Create playbook	Create a new playbook.
POST Create many playbooks	Create multiple new playbooks.
GET Get playbook	Get a playbook by ID.
PATCH Update playbook	Update a playbook by ID.
DELETE Delete playbook	Delete a playbook by ID.
GET Read playbook instructions	Read a page of a playbook’s instructions as numbered lines.
PATCH Patch playbook instructions	Replace an exact string in a playbook’s instructions.
POST Search playbook instructions	Search a playbook’s instructions with a regular expression.

Function

Endpoint	Description
GET List functions	List all functions by project ID.
POST Create function	Create a new function.
POST Create many functions	Create multiple new functions.
GET Get function	Get a function by ID.
PATCH Update function	Update a function by ID.
DELETE Delete function	Delete a function by ID.

Function path

Endpoint	Description
GET List paths	List all paths by function ID.
POST Create path	Create a new path.
POST Create many paths	Create multiple new paths.
GET Get path	Get a path by ID.
PATCH Update path	Update a path by ID.
DELETE Delete path	Delete a path by ID.

Function variable

Endpoint	Description
GET List variables	List all variables by function ID.
POST Create variable	Create a new variable.
POST Create many variables	Create multiple new variables.
GET Get variable	Get a variable by ID.
PATCH Update variable	Update a variable by ID.
DELETE Delete variable	Delete a variable by ID.

Tool

Endpoint	Description
GET List tools	List all tools for the agent or a specific playbook.
POST Create tool	Create a new tool.
POST Create many tools	Create multiple new tools.
GET Get tool	Get a tool by ID.
PATCH Update tool	Update a tool by ID.
DELETE Delete tool	Delete a tool by ID.

API tool

Endpoint	Description
GET List API tools	List all API tools by project ID.
POST Create API tool	Create a new API tool.
POST Create many API tools	Create multiple new API tools.
GET Get API tool	Get an API tool by ID.
PATCH Update API tool	Update an API tool by ID.
DELETE Delete API tool	Delete an API tool by ID.

API tool variable

Endpoint	Description
GET List variables	List all variables by API tool ID.
POST Create variable	Create a new variable.
POST Create many variables	Create multiple new variables.
GET Get variable	Get an variable by ID.
PATCH Update variable	Update an variable by ID.
DELETE Delete variable	Delete an variable by ID.

Variable

Endpoint	Description
GET List variables	List all variables by project ID.
POST Create variable	Create a new variable.
POST Create many variables	Create multiple new variables.
GET Get variable	Get a variable by ID.
PATCH Update variable	Update a variable by ID.
DELETE Delete variable	Delete a variable by ID.

MCP server

Endpoint	Description
GET List MCP servers	List all MCP servers by project ID.
POST Create MCP server	Create a new MCP server.
GET Get MCP server	Get an MCP server by ID.
PATCH Update MCP server	Update an MCP server by ID.
DELETE Delete MCP server	Delete an MCP server by ID.
PUT Sync MCP server	Sync tool changes for an MCP server by ID.

MCP tool

Endpoint	Description
GET List MCP tools	List all MCP tools by project ID.
GET Get MCP tool	Get an MCP tool by ID.

Secret

Endpoint	Description
GET List secrets	List all secrets by project ID.
POST Create secret	Create a new secret.
GET List secret overrides	List which secrets are overridden per environment version.
DELETE Delete secret	Delete a secret by ID.
PUT Set secret value	Set a secret value — the project-wide default, or an override on one environment version.

Integration

Endpoint	Description
GET List integrations	List every integration this project can use, along with whether it is currently connected.
POST Connect integration	Store credentials for an api-key integration on this project.
DELETE Disconnect integration	Clear every stored credential slot this integration owns on the project.

Knowledge base document

Endpoint	Description
GET List documents	List all documents by project ID.
POST Create URL document	Create a new document from a URL.
POST Create text document	Create a new document from raw text.
POST Create table document	Create a new document from structured data.
GET Get document	Get a document by ID.
PATCH Update document	Update a document by ID.
DELETE 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:

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 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 to make the changes live, and run a conversation against it to see how it behaves.

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks

Build overview