# Overview

> Voice agents that answer and place phone calls, configured and used entirely through an API.


# Allerto API

Allerto runs **voice agents** that talk on the phone in Italian or English. An agent either answers calls to your numbers (**inbound**) or calls people for you (**outbound**). After every call you receive what was said as structured data.

Everything is available in four equivalent ways, all built on the same schema:

| Way in          | Best for                      | Start here                        |
| --------------- | ----------------------------- | --------------------------------- |
| REST API        | Your backend                  | [API reference](/docs/reference/) |
| CLI (`allerto`) | Terminals, scripts, CI        | [CLI](/docs/cli/)                 |
| MCP server      | AI agents (Claude, Cursor, …) | [AI agents](/docs/ai-agents/)     |
| Console         | People configuring agents     | `https://api.allerto.cloud`       |

## Concepts

- **Account** — your company. It owns API keys, the webhook signing secret, the do-not-call list and billing.
- **Client** — an optional grouping for your own customers (`external_id`), used to split usage for re-billing. If you do not need it, ignore it: a default client is created for you.
- **Agent** — one JSON document describing a voice agent: who it is, what it says, what data it collects and where results go. It is edited as a **draft** and **published** as immutable versions. See [Agents](/docs/agents/).
- **Call** — one conversation, in either direction. Outbound calls exist from the moment they are queued and may take several attempts. See [Calls and campaigns](/docs/calls/).
- **Campaign** — many outbound calls with the same agent, queued and paced for you.
- **Outcome** — how a call ended: `completed`, `callback_requested`, `wrong_person`, `refused`, `do_not_call`, `hung_up`, `no_answer`, `busy`, `voicemail`, `suppressed`, `failed`, `cancelled`.
- **Event** — `call.completed` is sent to your webhook once per call, with the outcome and the extracted data. See [Webhooks](/docs/webhooks/).
- **Test mode** — keys starting with `alt_test_` never phone anyone. Test numbers produce predictable outcomes. See [Test mode](/docs/test-mode/).

## How a call flows

```
outbound:  POST /v1/calls ─▶ queue (hours, do-not-call, retries) ─▶ phone rings ─▶ conversation
inbound:   someone calls your number ────────────────────────────────────────────▶ conversation
                                                                                       │
           call.completed webhook ◀─ validated result ◀─ extraction ◀─ transcript ◀────┘
```

The same agent schema drives both directions, the console, the CLI and the MCP tools. What the console shows is exactly what the API accepts.

## Base URL and authentication

```http
https://api.allerto.cloud/v1
Authorization: Bearer alt_live_…
```

Create keys in the console under **Numbers and developers**. The full key is shown once. Live keys (`alt_live_…`) place real calls; test keys (`alt_test_…`) only simulate them.

Next: [Quickstart](/docs/quickstart/).