API reference
The complete, machine-readable contract is the OpenAPI 3.1 document at /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 |
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 for signatures and retries.
Agent JSON Schema
Also served at /v1/agents/schema.
{
"$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
}
]
}