# API reference > Every endpoint of the Allerto API, the agent JSON Schema and the machine-readable specification. # API reference The complete, machine-readable contract is the OpenAPI 3.1 document at [`/v1/openapi.json`](/v1/openapi.json). It is generated from the schemas the server validates with, so it always matches what the API accepts. Import it in Postman, Insomnia or any code generator. Base URL `https://api.allerto.cloud` · Authentication `Authorization: Bearer alt_live_…` (or `alt_test_…`) · JSON bodies · `Idempotency-Key` on every `POST`. ## Endpoints | Method | Path | Summary | | --- | --- | --- | | `GET` | `/v1/me` | The account and mode of this key | | `GET` | `/v1/agents` | List agents | | `POST` | `/v1/agents` | Create an agent (as a draft) | | `GET` | `/v1/agents/schema` | JSON Schema of the agent document | | `POST` | `/v1/agents/validate` | Validate an agent document without saving it | | `GET` | `/v1/agents/{id}` | Get an agent | | `PUT` | `/v1/agents/{id}/draft` | Save the draft | | `POST` | `/v1/agents/{id}/publish` | Publish the draft as a new immutable version | | `POST` | `/v1/agents/{id}/archive` | Archive an agent | | `PUT` | `/v1/agents/{id}/mcp-token` | Store the bearer token Allerto sends to the agent's MCP server (encrypted, never returned) | | `DELETE` | `/v1/agents/{id}/mcp-token` | Remove the MCP token | | `POST` | `/v1/agents/{id}/mcp-test` | Connect to the agent's MCP server and list the tools the agent would get | | `GET` | `/v1/agents/{id}/versions` | List published versions | | `GET` | `/v1/agents/{id}/versions/{version}` | Get a published version | | `POST` | `/v1/agents/{id}/preview` | Render the first sentence and prompt with example or given inputs (no call) | | `POST` | `/v1/calls` | Queue an outbound call | | `GET` | `/v1/calls` | List calls in both directions, newest first | | `GET` | `/v1/calls/{id}` | Get a call | | `GET` | `/v1/calls/{id}/transcript` | Get the transcript of a call | | `POST` | `/v1/calls/{id}/cancel` | Cancel a queued outbound call | | `POST` | `/v1/campaigns` | Create a campaign from a list of contacts | | `GET` | `/v1/campaigns` | List campaigns | | `GET` | `/v1/campaigns/{id}` | Get a campaign with its progress | | `POST` | `/v1/campaigns/{id}/pause` | Pause a campaign | | `POST` | `/v1/campaigns/{id}/resume` | Resume a campaign | | `POST` | `/v1/campaigns/{id}/cancel` | Cancel a campaign | | `GET` | `/v1/numbers` | List the account's numbers | | `PUT` | `/v1/numbers/{id}` | Route a number to an inbound agent | | `GET` | `/v1/suppressions` | List the do-not-call list | | `POST` | `/v1/suppressions` | Add a number to the do-not-call list | | `DELETE` | `/v1/suppressions/{number}` | Remove a number from the do-not-call list | | `POST` | `/v1/webhook-secret` | Create or rotate the account's webhook signing secret (shown once) | | `GET` | `/v1/events` | Recent events and their delivery status | | `GET` | `/v1/clients` | List clients | | `POST` | `/v1/clients` | Create a client (grouping for re-billing) | | `DELETE` | `/v1/clients/{id}` | Delete a client: its agents are archived, queued calls cancelled and its login removed; call and usage history is kept | | `GET` | `/v1/usage` | Monthly usage and bill | | `GET` | `/v1/usage/records` | One row per recorded call | | `POST` | `/mcp` | Model Context Protocol endpoint (JSON-RPC), see [AI agents](/docs/ai-agents/) | ## Webhook events | Event | Payload | | --- | --- | | `call.completed` | `{ id, type, version: "2", created_at, livemode, partner_id, call }` | | `call.attempt_failed` | Same shape; `call.next_attempt_at` is set | See [Webhooks](/docs/webhooks/) for signatures and retries. ## Agent JSON Schema Also served at [`/v1/agents/schema`](/v1/agents/schema). ```json { "$id": "https://api.allerto.cloud/v1/agents/schema", "title": "Allerto agent", "description": "An inbound or outbound voice agent. Edit it as a draft (PUT /v1/agents/{id}/draft) and publish a version (POST /v1/agents/{id}/publish).", "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "inbound" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "persona": { "type": "string", "minLength": 1, "maxLength": 80 }, "language": { "default": "it", "type": "string", "enum": [ "it", "en" ] }, "model": { "type": "string", "enum": [ "gpt-live-1", "gemini-3.8-live" ] }, "voice": { "type": "string", "enum": [ "alloy", "ash", "ballad", "beacon", "bossa", "cedar", "cinder", "coral", "delta", "echo", "gleam", "marin", "meridian", "quartz", "ripple", "sage", "shimmer", "stone", "tempo", "verse", "vesper", "willow", "Achernar", "Achird", "Algenib", "Algieba", "Alnilam", "Aoede", "Autonoe", "Callirrhoe", "Charon", "Despina", "Enceladus", "Erinome", "Fenrir", "Gacrux", "Iapetus", "Kore", "Laomedeia", "Leda", "Orus", "Puck", "Pulcherrima", "Rasalgethi", "Sadachbia", "Sadaltager", "Schedar", "Sulafat", "Umbriel", "Vindemiatrix", "Zephyr", "Zubenelgenubi" ] }, "customVoiceId": { "type": "string", "pattern": "^voice_[A-Za-z0-9_-]+$" }, "instructions": { "type": "string", "minLength": 10, "maxLength": 12000 }, "result": { "default": [], "maxItems": 40, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,49}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "enum": [ "text", "number", "boolean", "select", "date", "phone", "email" ] }, "required": { "default": false, "type": "boolean" }, "options": { "default": [], "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "when": { "type": "object", "properties": { "field": { "type": "string" }, "equals": { "type": [ "string", "number", "boolean" ] } }, "required": [ "field", "equals" ], "additionalProperties": false }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "key", "label", "type" ], "additionalProperties": false } }, "delivery": { "default": { "mode": "sandbox", "url": "" }, "type": "object", "properties": { "mode": { "type": "string", "enum": [ "sandbox", "webhook", "email", "both" ] }, "url": { "default": "", "type": "string", "maxLength": 2000 }, "email": { "type": "object", "properties": { "to": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "cc": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "subject": { "default": "Nuova richiesta · {{client_name}}", "type": "string", "minLength": 1, "maxLength": 250, "pattern": "^[^\\r\\n]+$" }, "introduction": { "default": "", "type": "string", "maxLength": 3000 }, "aiSummary": { "default": false, "type": "boolean" } }, "required": [ "to" ] } }, "required": [ "mode" ] }, "transfer": { "type": "object", "properties": { "to": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" }, "when": { "type": "string", "minLength": 3, "maxLength": 500 }, "hours": { "type": "object", "properties": { "days": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "from": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "to": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "required": [ "days", "from", "to" ], "additionalProperties": false }, "announcement": { "type": "string", "minLength": 3, "maxLength": 200 }, "musicUrl": { "type": "string", "maxLength": 500, "pattern": "^https:\\/\\/\\S+$" } }, "required": [ "to" ], "additionalProperties": false }, "mcp": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500, "pattern": "^https:\\/\\/\\S+$" }, "tools": { "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_.-]{0,63}$" } } }, "required": [ "url" ], "additionalProperties": false }, "recording": { "type": "boolean" }, "greeting": { "type": "string", "minLength": 10, "maxLength": 1000 }, "review": { "default": "on_issues", "type": "string", "enum": [ "on_issues", "always", "never" ] } }, "required": [ "type", "name", "persona", "instructions", "greeting" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "outbound" }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "persona": { "type": "string", "minLength": 1, "maxLength": 80 }, "language": { "default": "it", "type": "string", "enum": [ "it", "en" ] }, "model": { "type": "string", "enum": [ "gpt-live-1", "gemini-3.8-live" ] }, "voice": { "type": "string", "enum": [ "alloy", "ash", "ballad", "beacon", "bossa", "cedar", "cinder", "coral", "delta", "echo", "gleam", "marin", "meridian", "quartz", "ripple", "sage", "shimmer", "stone", "tempo", "verse", "vesper", "willow", "Achernar", "Achird", "Algenib", "Algieba", "Alnilam", "Aoede", "Autonoe", "Callirrhoe", "Charon", "Despina", "Enceladus", "Erinome", "Fenrir", "Gacrux", "Iapetus", "Kore", "Laomedeia", "Leda", "Orus", "Puck", "Pulcherrima", "Rasalgethi", "Sadachbia", "Sadaltager", "Schedar", "Sulafat", "Umbriel", "Vindemiatrix", "Zephyr", "Zubenelgenubi" ] }, "customVoiceId": { "type": "string", "pattern": "^voice_[A-Za-z0-9_-]+$" }, "instructions": { "type": "string", "minLength": 10, "maxLength": 12000 }, "result": { "default": [], "maxItems": 40, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,49}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "enum": [ "text", "number", "boolean", "select", "date", "phone", "email" ] }, "required": { "default": false, "type": "boolean" }, "options": { "default": [], "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "when": { "type": "object", "properties": { "field": { "type": "string" }, "equals": { "type": [ "string", "number", "boolean" ] } }, "required": [ "field", "equals" ], "additionalProperties": false }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "key", "label", "type" ], "additionalProperties": false } }, "delivery": { "default": { "mode": "sandbox", "url": "" }, "type": "object", "properties": { "mode": { "type": "string", "enum": [ "sandbox", "webhook", "email", "both" ] }, "url": { "default": "", "type": "string", "maxLength": 2000 }, "email": { "type": "object", "properties": { "to": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "cc": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "subject": { "default": "Nuova richiesta · {{client_name}}", "type": "string", "minLength": 1, "maxLength": 250, "pattern": "^[^\\r\\n]+$" }, "introduction": { "default": "", "type": "string", "maxLength": 3000 }, "aiSummary": { "default": false, "type": "boolean" } }, "required": [ "to" ] } }, "required": [ "mode" ] }, "transfer": { "type": "object", "properties": { "to": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" }, "when": { "type": "string", "minLength": 3, "maxLength": 500 }, "hours": { "type": "object", "properties": { "days": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "from": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "to": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "required": [ "days", "from", "to" ], "additionalProperties": false }, "announcement": { "type": "string", "minLength": 3, "maxLength": 200 }, "musicUrl": { "type": "string", "maxLength": 500, "pattern": "^https:\\/\\/\\S+$" } }, "required": [ "to" ], "additionalProperties": false }, "mcp": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 500, "pattern": "^https:\\/\\/\\S+$" }, "tools": { "maxItems": 20, "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_.-]{0,63}$" } } }, "required": [ "url" ], "additionalProperties": false }, "recording": { "type": "boolean" }, "opening": { "type": "string", "minLength": 10, "maxLength": 500 }, "inputs": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,49}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "enum": [ "text", "number", "boolean", "select", "date", "phone", "email" ] }, "required": { "default": false, "type": "boolean" }, "options": { "default": [], "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "when": { "type": "object", "properties": { "field": { "type": "string" }, "equals": { "type": [ "string", "number", "boolean" ] } }, "required": [ "field", "equals" ], "additionalProperties": false }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "key", "label", "type" ], "additionalProperties": false } }, "calling": { "default": { "identityCheck": true, "hours": { "days": [ 1, 2, 3, 4, 5, 6 ], "from": "09:00", "to": "20:00" }, "maxAttempts": 3, "autoCallback": true }, "type": "object", "properties": { "callerId": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" }, "identityCheck": { "default": true, "type": "boolean" }, "hours": { "default": { "days": [ 1, 2, 3, 4, 5, 6 ], "from": "09:00", "to": "20:00" }, "type": "object", "properties": { "days": { "default": [ 1, 2, 3, 4, 5, 6 ], "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "from": { "default": "09:00", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "to": { "default": "20:00", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "additionalProperties": false }, "maxAttempts": { "default": 3, "type": "integer", "minimum": 1, "maximum": 5 }, "autoCallback": { "default": true, "type": "boolean" } }, "additionalProperties": false }, "review": { "default": "never", "type": "string", "enum": [ "on_issues", "always", "never" ] } }, "required": [ "type", "name", "persona", "instructions", "opening" ], "additionalProperties": false } ] } ```