REST API
Build, test, ship and run agents from your own code over a versioned REST API, authenticated with a personal access token.
The Vertical AI API gives your servers and scripts everything the app, the MCP server and the Builder can do, under the same rules. It is generated from the same catalogue of operations, so a capability that reaches one reaches the others.
curl https://app.verticalai.com.au/api/v1/workspaces/acme/agents \
-H "Authorization: Bearer vai_pat_…"{
"data": [
{
"agent": "acme/front-desk",
"name": "Front desk",
"workspace": "acme",
"is_active": true,
"archived": false,
"published": true,
"updated_at": "2026-11-08T23:14:05.112Z"
}
],
"has_more": false,
"next_cursor": null
}Every route is in the API reference, and the OpenAPI 3.1
specification is at
/api/v1/openapi.json.
Authenticate
Create a personal access token in Settings > API tokens and send it as a bearer token on every request.
| Token setting | Lets it |
|---|---|
| View only (the default) | Read agents, calls, tests and settings |
| Edit | Also change agents, publish, run tests and spend credit, as far as your role allows |
| Also allow Delete | Delete things such as tools, versions, tests, campaigns, recipients and contacts, and permanently delete archived agents. Only an Edit token can have it |
| Also allow Manage the workspace | Members, phone numbers, webhooks and connected apps. Only an Edit token can have it |
| This workspace or All my workspaces | Which workspaces it reaches |
| Expires after 30 days, 90 days or 1 year | When it stops working. Revoke it sooner under the same settings |
A request runs as you, so your role in each workspace still applies: a viewer's
token cannot publish, whatever its access. A request the token's access does
not cover is refused with insufficient_scope, and required names the access
it needs.
Routes
Paths start at https://app.verticalai.com.au/api/v1. Workspaces and agents
are named by their slugs: GET /me lists your workspaces, and
GET /workspaces/{workspace}/agents lists a workspace's agents.
| Path | Holds |
|---|---|
/workspaces/{workspace}/agents/{agent} | The agent: read, change from a partial spec, archive, validate, message it |
…/versions, …/versions/publish | Open a draft and publish it |
…/tools, …/variables, …/secrets, …/knowledge-base | What the agent can call and know |
…/tests, …/test-runs, …/runs/{run}/transcript | Test scenarios, runs and results |
…/calls, …/calls/{call} | The agent's calls, each with transcript, metrics and analysis |
/workspaces/{workspace}/phone-numbers | Numbers and the agents they route to |
/workspaces/{workspace}/campaigns, …/contacts | Outbound campaigns and the contact list |
/workspaces/{workspace}/webhooks | Webhooks and their delivery log |
Every other operation is one POST to /operations/{name}, with the
operation's input as the JSON body. An operation on one agent takes the agent
as "agent": "workspace-slug/agent-slug":
curl https://app.verticalai.com.au/api/v1/operations/set_greeting_message \
-H "Authorization: Bearer vai_pat_…" \
-H "Content-Type: application/json" \
-d '{ "agent": "acme/front-desk", "greetingMessage": "Thanks for calling Acme Plumbing, this is Sam." }'The operation names are the same as the MCP server's tools, listed in the
tool reference. Any operation, including
one with its own route, also answers at /operations/{name}.
Inputs
A GET or DELETE reads its inputs from the query string: repeat a parameter
for a list (?tags=vip&tags=new). Other methods read a JSON body. A value the
path already sets, such as the agent, cannot also come from the body, and an
input the operation does not know is refused rather than ignored.
Changes land on a draft
A change to an agent's configuration is made to its latest draft. When the
agent's latest version is published, open a draft first with
POST …/versions, change it, then publish it with POST …/versions/publish.
Before each change you make, the draft is saved, and your newest ten saves are
kept for each agent. POST /operations/undo_last_change with { "agent": "acme/front-desk" }
puts the draft back the way it was before your last change, and "steps" goes
back up to ten. It never publishes. When putting the draft back would change
live calls at once or delete something, it answers 409
confirmation_required first, like any other change that asks.
Confirm before acting
Some operations delete something, publish, change what live callers hear
straight away, or spend credit on test calls. Without confirmation they change
nothing and answer 409 with the problem confirmation_required; one that
spends credit includes its estimate:
{
"type": "https://docs.verticalai.com.au/docs/platform/rest-api-errors#confirmation_required",
"title": "Confirmation required",
"status": 409,
"detail": "'POST /workspaces/{workspace}/agents/{agent}/test-runs' would start 30 billed runs (30 bridge) and was not confirmed. Estimate: about 60 call minutes, A$18.60 for call time, the agent's replies, call checks and grading. Test runs are not charged for post-call analysis. Tell the user the estimate, then re-call with confirm: true to proceed.",
"code": "confirmation_required",
"estimate": {
"runs": 30,
"text": 0,
"bridge": 30,
"phone": 0,
"voiceMinutes": 60,
"perMinuteCents": 25,
"costCents": 1860,
"covers": "call time, the agent's replies, call checks and grading",
"note": "Test runs are not charged for post-call analysis."
}
}costCents is in Australian cents. An estimate without it could not be priced;
it still gives the call minutes.
Send the same request again with "confirm": true in the body, or
?confirm=true on a DELETE, once the person responsible has agreed. The
reference marks these operations with x-vai-asks-first. The audit log
records a change confirmed this way as confirmed_by: api_client.
Retry safely
A POST can carry an Idempotency-Key header: a value you choose, such as
a UUID, of 1 to 255 visible ASCII characters. Send the same key again with the same
request within 24 hours and the API answers with the first answer instead of
running the operation again, marked Idempotent-Replayed: true. Use one key
per intended action, and reuse it only to retry that action.
curl https://app.verticalai.com.au/api/v1/workspaces/acme/agents/front-desk/duplicate \
-H "Authorization: Bearer vai_pat_…" \
-H "Idempotency-Key: 6c2f9a52-7d0e-4b9c-9f51-0c1e5f4f9a10" \
-H "Content-Type: application/json" \
-d '{ "name": "Front desk (after hours)" }'| Repeat | Answer |
|---|---|
| Same key, same request, first one succeeded | The first answer again, and nothing runs |
| Same key, same request, first one still running | 409 idempotency_key_in_use |
| Same key, same request, first one failed | It runs again: a failed request keeps nothing |
| Same key, different request | 422 idempotency_key_reused |
The request is the method, the path with its query string, and the JSON
body, whatever the order of its keys. Keys belong to you, across all your
tokens. Other methods ignore the header: PUT and DELETE are safe to
repeat as they are, and PATCH on an agent applies only what differs.
Pages
A list answers with its items in data, has_more, and next_cursor. Pass
next_cursor back as cursor for the next page, with the same filters, and
set the page size with limit (1 to 200, 50 by default; calls take up to 50).
Cursors are opaque: do not build or edit one.
Errors
Every error is an RFC 9457 problem
details object, sent as application/problem+json:
{
"type": "https://docs.verticalai.com.au/docs/platform/rest-api-errors#agent_not_found",
"title": "Not found",
"status": 404,
"detail": "No agent at 'acme/front-dsk' that you can access. Call GET /workspaces/{workspace}/agents to see your agents (and their exact workspace/slug handles), or POST /workspaces/{workspace}/agents to make a new one. If you expected this agent to exist, double-check the workspace slug with GET /me.",
"code": "agent_not_found"
}Branch on code, which is stable; detail says what to change and may be
reworded. A refused input also carries errors, one { path, message } for
each field. Every code is listed in API errors.
Rate limits
Each access token may make 600 requests a minute to the REST API. The MCP server keeps its own count, apart from this one: 1,200 requests a minute for each connection, where all of one person's access tokens count as one connection. Every REST answer says where the token stands, in the IETF RateLimit fields:
RateLimit-Policy: "token";q=600;w=60
RateLimit: "token";r=587;t=41r is the requests left and t the seconds until the window resets. Over the
limit, a request answers 429 with Retry-After and the problem
rate_limited, and changes nothing. Wait the seconds it gives, then try
again.
Webhook events
The specification's webhooks section describes the body of every event a
webhook receives, and the X-VAI-Signature and
X-VAI-Event-Id headers each delivery carries. Each body is
{ id, event, data }; data depends on the event. A test delivery can carry
any event name, and its data is always { test: true, workspaceId, timestamp }.
Versions
The v1 in the path is the API's major version. Within it, routes, operations,
inputs and answer fields are only added: nothing is renamed or removed and no
answer changes shape. A breaking change ships as v2, with notice.
Client libraries
The TypeScript SDK (@verticalai.com.au/sdk) and the
Python SDK (vertical-ai) are generated from this
specification, so every route and operation is a typed function. For any other
language, the specification works with any OpenAPI 3.1 client generator.
Audit
Every change made through the API is recorded in the workspace's audit log against the token that made it.