API reference
Base URL https://api.airfone.app. Version 2026-10-04. Authenticate with Authorization: Bearer af_sk_.... Download the OpenAPI document.
Fallback copy committed with the portal. The build replaces it with the live document when AIRFONE_OPENAPI_URL is set.
Calls
GET/v1/calls
List calls.
Scope calls:read
| Parameter | In | Description |
|---|---|---|
limit | query | 1 to 100, default 20 |
starting_after | query | Cursor from the previous page |
POST/v1/calls
Start an outbound AI call.
Scope calls:write
| Parameter | In | Description |
|---|---|---|
Idempotency-Key | header | Makes a retried POST safe. Any unique string, kept 24 hours. |
| Body field | Type | Description |
|---|---|---|
to | string | E.164 number to call |
agent_id | string | Assistant that handles the call |
from | string | Your AirFone number, E.164 |
context | object | Facts the assistant may use on this call |
metadata | object | Your own key-value pairs, returned in webhooks |
GET/v1/calls/{id}
Get a call.
Scope calls:read
| Parameter | In | Description |
|---|---|---|
id (required) | path | Call id, call_... |
POST/v1/calls/{id}/transfer
Transfer a live call.
Scope calls:write
| Parameter | In | Description |
|---|---|---|
id (required) | path | Call id |
Idempotency-Key | header | Makes a retried POST safe. Any unique string, kept 24 hours. |
| Body field | Type | Description |
|---|---|---|
to | string | Number or user to transfer to |
POST/v1/calls/{id}/end
End a live call.
Scope calls:write
| Parameter | In | Description |
|---|---|---|
id (required) | path | Call id |
Idempotency-Key | header | Makes a retried POST safe. Any unique string, kept 24 hours. |
GET/v1/calls/{id}/transcript
Get a call transcript.
Scope calls:read
| Parameter | In | Description |
|---|---|---|
id (required) | path | Call id |
POST/v1/bulk-calls
Start a bulk call campaign.
Scope calls:write
| Parameter | In | Description |
|---|---|---|
Idempotency-Key | header | Makes a retried POST safe. Any unique string, kept 24 hours. |
| Body field | Type | Description |
|---|---|---|
agent_id | string | Assistant |
form_id | string | Form to fill on each call |
contacts | array | Numbers to call |
Messages
POST/v1/messages
Send a message.
Scope messages:write
| Parameter | In | Description |
|---|---|---|
Idempotency-Key | header | Makes a retried POST safe. Any unique string, kept 24 hours. |
| Body field | Type | Description |
|---|---|---|
channel | string | whatsapp or sms |
to | string | E.164 number |
text | string | Message text |
template | object | WhatsApp template name, language and parameters, required outside the 24 hour window |
GET/v1/conversations
List conversations.
Scope messages:read
GET/v1/conversations/{id}/messages
List messages in a conversation.
Scope messages:read
| Parameter | In | Description |
|---|---|---|
id (required) | path | Conversation id |
Agents
GET/v1/agents
List assistants.
Scope agents:read
POST/v1/knowledge
Add a knowledge document.
Scope agents:write
| Parameter | In | Description |
|---|---|---|
Idempotency-Key | header | Makes a retried POST safe. Any unique string, kept 24 hours. |
| Body field | Type | Description |
|---|---|---|
agent_id | string | Assistant |
title | string | Title |
text | string | Content |
Contacts
GET/v1/contacts
List contacts.
Scope contacts:read
POST/v1/contacts
Create or update a contact.
Scope contacts:write
| Parameter | In | Description |
|---|---|---|
Idempotency-Key | header | Makes a retried POST safe. Any unique string, kept 24 hours. |
| Body field | Type | Description |
|---|---|---|
phone | string | E.164 |
name | string | Name |
external_id | string | Your id for this person |
POST/v1/records
Push records about a contact.
Scope records:write
| Parameter | In | Description |
|---|---|---|
Idempotency-Key | header | Makes a retried POST safe. Any unique string, kept 24 hours. |
| Body field | Type | Description |
|---|---|---|
contact | object | phone or external_id |
records | array | Records shown to staff and given to the assistant |
Webhooks
GET/v1/webhook-endpoints
List webhook endpoints.
Scope webhooks:read
POST/v1/webhook-endpoints
Create a webhook endpoint.
Scope webhooks:write
| Parameter | In | Description |
|---|---|---|
Idempotency-Key | header | Makes a retried POST safe. Any unique string, kept 24 hours. |
| Body field | Type | Description |
|---|---|---|
url | string | HTTPS URL |
events | array | Event types, or ["*"] |
GET/v1/events
List events.
Scope events:read
Usage
GET/v1/usage
Get usage for a period.
Scope usage:read
| Parameter | In | Description |
|---|---|---|
from | query | ISO date |
to | query | ISO date |
Connectors
GET/v1/connectors
List connectors you publish.
Scope connectors:read
POST/v1/connectors/{id}/versions
Upload a connector version.
Scope connectors:write
| Parameter | In | Description |
|---|---|---|
id (required) | path | Connector id, reverse DNS |
Idempotency-Key | header | Makes a retried POST safe. Any unique string, kept 24 hours. |
| Body field | Type | Description |
|---|---|---|
bundle | string | Signed tar bundle, base64 |
signature | string | Ed25519 signature of the bundle's sha256 |
Widget
POST/v1/widget/session
Open a widget session.
Called by widget.js with a publishable key.
| Body field | Type | Description |
|---|---|---|
visitor_id | string | Stable id for this browser |
identity | object | user_id and user_hash for a verified visitor |
POST/v1/widget/messages
Send a widget message.
| Parameter | In | Description |
|---|---|---|
Idempotency-Key | header | Makes a retried POST safe. Any unique string, kept 24 hours. |
| Body field | Type | Description |
|---|---|---|
text | string | Visitor's message |
GET/v1/widget/stream
Stream widget events (SSE).
| Parameter | In | Description |
|---|---|---|
token (required) | query | Session token |
POST/v1/widget/voice
Start a browser voice call.
Returns a LiveKit URL, room and token. The assistant joins the room.