Connect

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 settingLets it
View only (the default)Read agents, calls, tests and settings
EditAlso change agents, publish, run tests and spend credit, as far as your role allows
Also allow DeleteDelete 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 workspaceMembers, phone numbers, webhooks and connected apps. Only an Edit token can have it
This workspace or All my workspacesWhich workspaces it reaches
Expires after 30 days, 90 days or 1 yearWhen 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.

PathHolds
/workspaces/{workspace}/agents/{agent}The agent: read, change from a partial spec, archive, validate, message it
…/versions, …/versions/publishOpen a draft and publish it
…/tools, …/variables, …/secrets, …/knowledge-baseWhat the agent can call and know
…/tests, …/test-runs, …/runs/{run}/transcriptTest scenarios, runs and results
…/calls, …/calls/{call}The agent's calls, each with transcript, metrics and analysis
/workspaces/{workspace}/phone-numbersNumbers and the agents they route to
/workspaces/{workspace}/campaigns, …/contactsOutbound campaigns and the contact list
/workspaces/{workspace}/webhooksWebhooks 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)" }'
RepeatAnswer
Same key, same request, first one succeededThe first answer again, and nothing runs
Same key, same request, first one still running409 idempotency_key_in_use
Same key, same request, first one failedIt runs again: a failed request keeps nothing
Same key, different request422 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=41

r 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.

On this page