Connect

Python SDK

Call the REST API from Python with a typed function for every route and operation, sync or async, generated from the API's OpenAPI specification.

vertical-ai is the REST API as typed Python functions. It is generated from the API's OpenAPI specification, so every route and every operation has a module, and every body and answer is a typed model.

pip install vertical-ai

It needs Python 3.10 or later. The package imports as vertical_ai.

Authenticate

Create a personal access token under Settings > API tokens, with the access your code needs: View only to read, Edit to change agents and run tests. Keep it in an environment variable, never in the code.

import os

from vertical_ai import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://app.verticalai.com.au/api/v1",
    token=os.environ["VAI_TOKEN"],
)

The first call

from vertical_ai.api.agents import list_agents
from vertical_ai.models.problem import Problem

agents = list_agents.sync("acme", client=client)
if isinstance(agents, Problem):
    raise SystemExit(f"{agents.code}: {agents.detail}")

for agent in agents.data:
    print(agent.agent, agent.name, "published" if agent.published else "draft only")

Each route and operation is a module under vertical_ai.api, grouped by the API reference's sections, named after its operation: GET /workspaces/{workspace}/agents is vertical_ai.api.agents.list_agents. Each module has four functions:

FunctionAnswers
syncThe parsed answer, or a Problem
sync_detailedA Response with status_code, headers and parsed
asyncio, asyncio_detailedThe same, to await

Path parameters come first, in order; everything else is a keyword argument. A body is a model from vertical_ai.models. An operation without its own route is under vertical_ai.api.operations and takes the agent in its body:

from vertical_ai.api.operations import set_greeting_message
from vertical_ai.models.set_greeting_message_body import SetGreetingMessageBody

set_greeting_message.sync(
    client=client,
    body=SetGreetingMessageBody(
        agent="acme/front-desk",
        greeting_message="Thanks for calling Acme Plumbing, this is Sam.",
    ),
)

A change lands on the agent's draft. When the latest version is published, open a draft first with vertical_ai.api.versions.create_draft.

Errors

An error answers a Problem, the API's problem details: code, detail, status, and errors, estimate or retry_after_seconds when they apply. Branch on code, which is stable, and show detail to a person. A change that deletes something, publishes, changes live calls at once or spends credit answers confirmation_required until you send confirm=True:

from vertical_ai.api.versions import publish_version
from vertical_ai.models.publish_version_body import PublishVersionBody

first = publish_version.sync("acme", "front-desk", client=client, body=PublishVersionBody())
if isinstance(first, Problem) and first.code == "confirmation_required":
    print(first.detail)
    publish_version.sync("acme", "front-desk", client=client, body=PublishVersionBody(confirm=True))

Send confirm=True only once the person responsible has agreed. A test run's refusal carries its cost in estimate.

Pages

A list answers data, has_more and next_cursor. Pass next_cursor back as cursor, with the same filters, until it is None:

from vertical_ai.api.calls import list_calls
from vertical_ai.types import UNSET

cursor = UNSET
while True:
    page = list_calls.sync("acme", "front-desk", client=client, limit=50, cursor=cursor)
    if isinstance(page, Problem):
        raise SystemExit(f"{page.code}: {page.detail}")
    for call in page.data:
        print(call.session_id)
    if not page.next_cursor:
        break
    cursor = page.next_cursor

Retry safely

Give a POST an idempotency_key so a retry after a timeout cannot run it twice. The API answers a repeat of the same request within 24 hours with the first answer. Retry safely has the rules.

import uuid

from vertical_ai.api.agents import duplicate_agent
from vertical_ai.models.duplicate_agent_body import DuplicateAgentBody

key = str(uuid.uuid4())
copy = duplicate_agent.sync(
    "acme",
    "front-desk",
    client=client,
    body=DuplicateAgentBody(name="Front desk (after hours)"),
    idempotency_key=key,
)

Keep the key with the job, and send the same key when you retry it.

Rate limits

Each token may make 600 requests a minute. sync_detailed returns the headers, and headers["RateLimit"] says how many are left. Over the limit, the Problem has the code rate_limited, and retry_after_seconds says how long to wait.

On this page