Programmatic access
Reach Vertical AI from code through the REST API, the MCP server or the website widgets, each with its own credential and reach.
Vertical AI has two machine interfaces with the same capabilities and the same checks: the REST API for your own servers and scripts, and the MCP server for AI assistants. Both run the same catalogue of operations.
| Surface | Credential | Reaches |
|---|---|---|
REST API app.verticalai.com.au/api/v1 | Personal access token (vai_pat_…) | Everything you can do in your workspaces: agents, tools, variables, knowledge, tests, calls, phone numbers, campaigns, contacts, webhooks |
MCP server app.verticalai.com.au/api/mcp | Bearer token from the sign-in flow, or a personal access token | The same, for an AI assistant |
| vai CLI | A personal access token that vai login makes, or VAI_TOKEN | Every MCP tool from a terminal or CI, plus config as code and test runs |
| TypeScript and Python SDKs | Personal access token | The REST API as typed functions |
| Website widgets | Publishable key (pk_live_ / pk_test_) | One agent, on the origins that key allows |
Personal access tokens
Create one in Settings > API tokens. A new token is View only. Choose Edit to let it make changes, and tick Delete or Manage the workspace only if it needs them. It reaches the workspace you make it in, or all your workspaces if you choose. It expires after 30 days, 90 days (the default) or a year, and you can revoke it at any time. It runs as you, so your role in each workspace still applies.
vai login makes a token for you through the browser. Its approval page starts
at read and write instead, because that is what vai push and vai test
need, and its token lasts 90 days.
Scopes
The MCP sign-in flow and personal access tokens grant the same four scopes.
Read-only is the default for both. A grant that can write may leave out
agent:delete, workspace:admin or both. A refusal for a missing scope names
the scope and how to grant it.
| Scope | Grants |
|---|---|
agent:read | List and inspect agents, transcripts, readiness |
agent:write | Edit agents, create drafts, publish, run tests, and manage campaigns and contacts |
agent:delete | Delete tools, versions, tests, variables, knowledge sources, campaigns, recipients and contacts, revoke publishable keys, and permanently delete archived agents |
workspace:admin | Members, phone numbers, webhooks, connected apps, trusted callers, and the workspace's name, slug and settings |
Destructive operations
Anything that destroys data, publishes, changes what live callers get straight
away, or spends credit on test calls needs an explicit confirm: true on the
call. Without it nothing changes: the MCP server asks for confirmation, and the
REST API answers 409 confirmation_required, with a cost estimate when the
call spends credit. The estimate says what it covers: call time, the agent's
replies, call checks and grading for test runs, and post-call analysis for
real calls. When your MCP client supports elicitation, the server asks you in
the client instead and ignores confirm: true from the assistant.
Rate limits
Each personal access token may make 600 requests a minute on the REST API. The MCP server counts separately: 1,200 requests a minute for each connection, and all of one person's access tokens count as one connection there. See Rate limits.
Audit trail
Every successful change writes an append-only audit entry naming the token or connection that made it. See Access control.
Publishable keys
A publishable key authenticates the website widgets. It is scoped to one agent and carries an origin allowlist. It cannot read or change agent settings.