Connect

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.

SurfaceCredentialReaches
REST API app.verticalai.com.au/api/v1Personal 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/mcpBearer token from the sign-in flow, or a personal access tokenThe same, for an AI assistant
vai CLIA personal access token that vai login makes, or VAI_TOKENEvery MCP tool from a terminal or CI, plus config as code and test runs
TypeScript and Python SDKsPersonal access tokenThe REST API as typed functions
Website widgetsPublishable 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.

ScopeGrants
agent:readList and inspect agents, transcripts, readiness
agent:writeEdit agents, create drafts, publish, run tests, and manage campaigns and contacts
agent:deleteDelete tools, versions, tests, variables, knowledge sources, campaigns, recipients and contacts, revoke publishable keys, and permanently delete archived agents
workspace:adminMembers, 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.

On this page