v2.app.bland.ai. Every endpoint here mirrors something the agent builder does: saving a configuration, publishing it to an environment, branching to try a change, or routing a phone number to an agent.
It does not replace the rest of the Bland API. Calls, numbers, knowledge bases, tools, and everything else still live in the API Reference tab, and those endpoints are unchanged.
How an agent is structured
Most of this API follows from four ideas, so it is worth reading these before the endpoint pages. An agent is an org-scoped record. Creating one gives you three empty environments and nothing else, because an agent holds no configuration of its own. A version is a complete agent configuration, saved and never modified afterwards. Saving a version does not deploy it. Environments aredev, staging, and production. Each one pins a single version. Publishing moves the staging pin, promoting moves the production pin, and rolling back moves it to an earlier version. Calls run whatever version the environment currently pins.
Branches are dev workspaces. Save onto a branch to work without touching the dev timeline, then rebase and merge it back.
Three features build on those: checks gate promotions, experiments run a variant against an environment’s pin, and dispositions classify call outcomes. Dispositions are enabled per organization.
Base URL and authentication
Every route lives underhttps://api.bland.ai/v2/agents. Send your API key in the authorization header.
A successful response returns your payload in data with errors set to null. On any error, data is null and errors carries one or more entries with an error code and a message.
Success
Error
Where to start
If you have not built an agent yet, Build your first agent walks through the dashboard first, which makes these endpoints easier to follow. To create one over the API, the shortest path to a live agent is Create Agent, then Create Agent Version, then Publish Agent and Promote Agent.Docs for agents: llms.txt