> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getvoxai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getvoxai.com/_mcp/server.

# Introduction

The VoxAI public API (v1) lets your systems read what your voice agents do and act on it: calls and their transcripts, agents, campaigns, the knowledge base, usage, webhooks and the requests of the people who call you. Everything you can do here is limited to one Organization, the one that owns the API key.

## Base URL

```
https://api.getvoxai.com/v1
```

Every request uses HTTPS. A plain HTTP request gets `400 https_required`.

## Keys: live and test

You authenticate with an API key created in the app (Sviluppatori, then Accesso) by an Owner or an Admin. A key belongs to one environment:

| Environment | Prefix     | What happens                                                                                                                   |
| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Live        | `vx_live_` | Real reads and writes. Operations that cost (calls, campaigns, indexing) use minutes.                                          |
| Test        | `vx_test_` | Reads return the Organization's real data. Writes are simulated: every check runs, then nothing is done and nothing is billed. |

See [Authentication](/introduction/authentication) for scopes, rotation and revocation.

## Conventions

* **JSON everywhere.** Request and response bodies are JSON, encoded in UTF-8. Field names of resources are in `snake_case`. Error bodies keep a few names in camelCase: `requestId`, and `retryAfterSec` in the `details` of a `429`.
* **Every object says what it is.** Each resource has an `object` field (`call`, `agent`, `campaign`…) and a string `id`. Treat ids as opaque.
* **Dates** are ISO 8601 strings in UTC, with milliseconds: `2026-10-01T10:03:00.123Z`. Where a time zone matters (calling hours, schedules) it is an IANA name, such as `Europe/Rome`.
* **Phone numbers** are in international format: `+390458012310`.
* **Lists** use cursor pagination: `data`, `has_more`, `next_cursor`. See [Pagination](/concepts/pagination).
* **Writes** take an `Idempotency-Key` header, required on `POST`. See [Idempotency](/concepts/idempotency).
* **Errors** always have the same shape and a stable `code`. See [Errors](/concepts/errors).
* **No costs or prices.** Responses report units (minutes, SMS, calls), never amounts of money.

## Versions

The API version is a date. Today the only version is `2026-10-01`. Each key is pinned to the version that was current when it was created; the optional `VoxAI-Version` header overrides it for a single request. Every response to an accepted key states the version it used in `VoxAI-Version` (a `401` does not have it). A version is only extended, never changed: removing something from an existing version comes with 12 months' notice. See the [Changelog](/changelog).

## OpenAPI specification

The whole API is described by an OpenAPI 3.1 document, public and without authentication:

```
https://api.getvoxai.com/v1/openapi.json
```

Use it to generate a client or to import the API into your tools. The **API Reference** on this site is built from the same document.

## Next steps

* [Quickstart](/introduction/quickstart): from a key to the first response in five minutes.
* [Webhooks](/concepts/webhooks): receive events instead of polling.
* [MCP server](/concepts/mcp-server): connect an AI assistant to your Organization.