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

# Quickstart

The app is in Italian: its labels are written here as you see them. In five minutes you go from an API key to the first response of the v1 public API. You need an Owner or an Admin of the Organization and a plan that includes the public API.

## 1. Create a key

1. Sign in to the app as an Owner or an Admin.
2. Open **Sviluppatori** (Developers), then **Accesso** (Access).
3. Create a new key: choose a name, the environment and the scopes.
4. Copy the key right away. It is shown **only once** and cannot be recovered: if you lose it, create a new one or rotate it.

For this guide you need:

* the **test** environment (`vx_test_…`), or the **live** one (`vx_live_…`);
* the `calls:read` scope (Read calls).

A test key reads the Organization's real data but never writes: writes are simulated, call nobody and cost nothing. It is the safest way to start.

If the public API is not included in the plan, every request with a valid key gets `403 feature_not_available`.

## 2. Check the key

`GET /v1/me` answers to any valid key and shows its scopes, expiry and request limits.

```bash
curl https://api.getvoxai.com/v1/me \
  -H "Authorization: Bearer $VOXAI_API_KEY"
```

The response looks like this:

```json
{
  "object": "api_key",
  "id": "…",
  "prefix": "vx_test_ab3k7x2q",
  "name": "CRM",
  "environment": "test",
  "scopes": ["calls:read"],
  "api_version": "2026-10-01",
  "expires_at": "2027-10-01T00:00:00.000Z",
  "allowed_ips": [],
  "organization": { "id": "…", "name": "…" },
  "rate_limits": { "per_key_per_minute": 600, "per_organization_per_minute": 1200 }
}
```

If you get `401 invalid_api_key`, check that you copied the whole key. See [Authentication](/introduction/authentication).

## 3. Read the latest calls

`GET /v1/calls` returns the Organization's calls, most recent first. Here we ask for the last five.

#### curl

```bash
curl "https://api.getvoxai.com/v1/calls?limit=5" \
  -H "Authorization: Bearer $VOXAI_API_KEY"
```

#### Node.js

```js
const response = await fetch("https://api.getvoxai.com/v1/calls?limit=5", {
  headers: { Authorization: `Bearer ${process.env.VOXAI_API_KEY}` },
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(`${error.code} (request ${error.requestId})`);
}

const { data, has_more, next_cursor } = await response.json();
for (const call of data) {
  console.log(call.id, call.status, call.duration_seconds);
}
```

#### Python

```python
import os
import requests

response = requests.get(
    "https://api.getvoxai.com/v1/calls",
    params={"limit": 5},
    headers={"Authorization": f"Bearer {os.environ['VOXAI_API_KEY']}"},
    timeout=30,
)

if not response.ok:
    error = response.json()
    raise RuntimeError(f"{error['code']} (request {error.get('requestId')})")

body = response.json()
for call in body["data"]:
    print(call["id"], call["status"], call["duration_seconds"])
```

Each item of `data` is a call:

```json
{
  "object": "call",
  "id": "call-3",
  "started_at": "2026-10-01T10:03:00.123Z",
  "ended_at": "2026-10-01T10:03:40.000Z",
  "duration_seconds": 40,
  "direction": "inbound",
  "status": "completed",
  "caller_number": "+390458012300",
  "line_number": "+390458012310",
  "agent": { "id": "a1", "name": "Reception" },
  "handoff_count": 0,
  "report_card": { "status": "evaluated", "outcome": "needs_review" }
}
```

`report_card` is the call's Report card. If `has_more` is `true`, pass `next_cursor` as `cursor` to read the next page: see [Pagination](/concepts/pagination).

## 4. What to look at in the responses

* `X-Request-Id`: the id of the request. Quote it when you write to support.
* `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`: the requests you have left.
* `VoxAI-Version`: the API version used. Today only `2026-10-01` exists.

## Next steps

* [Authentication](/introduction/authentication): scopes, rotation and revocation of keys.
* [Idempotency](/concepts/idempotency): how to safely repeat requests that write.
* [Errors](/concepts/errors): the shape of error responses and every code.
* [Webhooks](/concepts/webhooks): receive events instead of polling the API.
* The **API Reference** describes every route, with parameters and responses.