Allomi, your AI phone assistant with a real number

The REST API lives under https://api.allomi.ai/v1 (or your own server when you self-host). The OpenAPI 3.1 file is packages/contracts/openapi.yaml in the repository, and this page is generated from it.

Authentication

Send an API key as a bearer token. Keys are created in the app (Connectors and API) or with POST /v1/api-keys, and carry scopes. Each operation below lists the scope it needs.

Authorization: Bearer alm_live_…

Errors

Every non-2xx response has the same body, and a Request-Id header you can quote to the support.

{ "error": { "type": "invalid_request", "code": "validation_error", "message": "prompt is required", "param": "prompt", "requestId": "req_…" } }

Pagination

List endpoints return { "data": [...], "nextCursor": "…" | null }, newest first. Pass cursor with the previous nextCursor to get the next page, and limit (1 to 100, default 20) to size it.

Idempotency

POST endpoints that create resources accept an Idempotency-Key header. The same key with the same body returns the first response for 24 hours (with Idempotent-Replayed: true). The same key with another body returns 409 idempotency_conflict.

Endpoints

Allomi API 0.1.0 · generated from openapi.yaml

Calls

GET`/v1/calls`

List calls

Key scope: calls:read

Parameters

Field	Type	Description
`limit (query)`	`integer`	Page size (1 to 100, default 20)
`cursor (query)`	`string`	Opaque cursor from `nextCursor` of the previous page
`status (query)`	`CallStatus`
`direction (query)`	`CallDirection`
`contactId (query)`	`string (uuid)`	Resource id (UUIDv7)

Responses

200 Calls, newest first CallList
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/calls`

Create a call

Key scope: calls:write

Places an outbound call driven by a free `prompt`. Calls to contacts need the `callable` permission; calls to other numbers need a number the account verified. Hourly, daily and minute caps apply. The result (status, duration, transcript, summary) arrives by webhook and on `GET /v1/calls/{callId}`.

Parameters

Field	Type	Description
`Idempotency-Key (header)`	`string`	Makes the POST safe to retry: the same key with the same body returns the first response for 24 hours (with `Idempotent-Replayed: true`); the same key with another body returns 409 `idempotency_conflict`.

Request body `CreateCallRequest`

Field	Type	Description
`to`	`E164`	Number to call. Exactly one of `to`, `contactId` or `owner` is required
`contactId`	`string (uuid)`	Contact to call (must have the `callable` permission)
`owner`	`true`	Call the account owner on their own phone ("call me")
`prompt` (required)	`string`	What the assistant must do on this call, in natural language
`language`	`Language`	Defaults to the contact's language, then the assistant's
`voice`	`string`
`maxMinutes`	`integer`	Default: 10. Range: 1 to 60.
`useContactMemory`	`boolean`	Give the assistant the contact's notes and history Default: true.
`reportToOwner`	`boolean`	Mission: when the call ends, report the result to the owner (in their ongoing call if they are on the line, otherwise by calling them back). Needs `contactId` with the `missionsAllowed` permission Default: false.
`webhookUrl`	`string (uri)`	Receives this call's events in addition to the account's webhook endpoints
`metadata`	`Metadata`	Free key/value strings attached by the developer (max 20 keys). Returned as is, never spoken.

Responses

201 The call, usually `queued` Call
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
402 Minute budget exhausted (`quota_exceeded`) Error
403 The API key lacks the required scope Error
404 Contact not found Error
409 Idempotency key reused with another body Error
422 Call policy refused the call (`policy_violation`) Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

GET`/v1/calls/{callId}`

Get a call (with transcript)

Key scope: calls:read

Parameters

Field	Type	Description
`callId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 The call Call
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Call not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/calls/{callId}/hangup`

Hang up a call

Key scope: calls:write

Ends a ringing or ongoing call. A no-op on a call that already ended.

Parameters

Field	Type	Description
`callId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 The call Call
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Call not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/calls/{callId}/say`

Say something in an ongoing call

Key scope: calls:write

Injects information the assistant relays in its own words. Treated as data, never as instructions.

Parameters

Field	Type	Description
`callId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Request body `SayInCallRequest`

Field	Type	Description
`text` (required)	`string`	What the assistant says now, as information to relay
`interrupt`	`boolean`	Cut the assistant off if it is speaking Default: false.

Responses

202 Queued for the assistant Accepted
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Call not found Error
409 The call is not in progress (`conflict`) Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

Asks

Ask a human by phone (ask_owner, ask_contact)

GET`/v1/asks`

List asks

Key scope: asks:read

Parameters

Field	Type	Description
`limit (query)`	`integer`	Page size (1 to 100, default 20)
`cursor (query)`	`string`	Opaque cursor from `nextCursor` of the previous page
`status (query)`	`"pending" \| "calling" \| "answered" \| "unanswered" \| "expired" \| "failed" \| "canceled"`

Responses

200 Asks, newest first AskList
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/asks`

Ask a human by phone (ask_owner / ask_contact)

Key scope: asks:write

Calls the owner (`target: owner`) or a contact (`target: contact`), reads the question, collects the answer and returns it by webhook (`ask.answered` / `ask.expired`) and on `GET /v1/asks/{askId}`.

Parameters

Field	Type	Description
`Idempotency-Key (header)`	`string`	Makes the POST safe to retry: the same key with the same body returns the first response for 24 hours (with `Idempotent-Replayed: true`); the same key with another body returns 409 `idempotency_conflict`.

Request body `CreateAskRequest`

Responses

201 The ask, `pending` Ask
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Contact not found Error
409 Idempotency key reused with another body Error
422 Call policy refused the call Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

GET`/v1/asks/{askId}`

Get an ask

Key scope: asks:read

Parameters

Field	Type	Description
`askId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 The ask Ask
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Ask not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/asks/{askId}/cancel`

Cancel an ask

Key scope: asks:write

Parameters

Field	Type	Description
`askId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 The ask, `canceled` Ask
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Ask not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

Schedules

GET`/v1/schedules`

List schedules

Key scope: schedules:read

Parameters

Field	Type	Description
`limit (query)`	`integer`	Page size (1 to 100, default 20)
`cursor (query)`	`string`	Opaque cursor from `nextCursor` of the previous page
`status (query)`	`ScheduleStatus`

Responses

200 Schedules, newest first ScheduleList
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/schedules`

Schedule a call (one-off or recurring)

Key scope: schedules:write

Parameters

Field	Type	Description
`Idempotency-Key (header)`	`string`	Makes the POST safe to retry: the same key with the same body returns the first response for 24 hours (with `Idempotent-Replayed: true`); the same key with another body returns 409 `idempotency_conflict`.

Request body `CreateScheduleRequest`

Field	Type	Description
`contactId`	`string (uuid)`	Omit to call the owner
`prompt` (required)	`string`
`rrule`	`string`	RFC 5545 recurrence rule, evaluated in `timezone`
`runAt`	`string (date-time)`	RFC 3339 date-time
`timezone`	`string`	IANA time zone Default: "Europe/Paris".
`language`	`Language`	BCP 47 language tag (language, optional region)
`voice`	`string`
`maxMinutes`	`integer`	Default: 10. Range: 1 to 60.
`metadata`	`Metadata`	Free key/value strings attached by the developer (max 20 keys). Returned as is, never spoken.

Responses

201 The schedule Schedule
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Contact not found Error
409 Idempotency key reused Error
422 Schedule refused (rule too frequent, or `runAt` in the past) Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

GET`/v1/schedules/{scheduleId}`

Get a schedule

Key scope: schedules:read

Parameters

Field	Type	Description
`scheduleId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 The schedule Schedule
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Schedule not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

PATCH`/v1/schedules/{scheduleId}`

Update, pause or resume a schedule

Key scope: schedules:write

Parameters

Field	Type	Description
`scheduleId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Request body `UpdateScheduleRequest`

Field	Type	Description
`status`	`"active" \| "paused"`
`prompt`	`string`
`rrule`	`string \| null`
`runAt`	`string (date-time) \| null`
`timezone`	`string`	IANA time zone
`language`	`Language \| null`
`voice`	`string \| null`
`maxMinutes`	`integer`	Range: 1 to 60.
`metadata`	`Metadata`	Free key/value strings attached by the developer (max 20 keys). Returned as is, never spoken.

Responses

200 The schedule Schedule
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Schedule not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

DELETE`/v1/schedules/{scheduleId}`

Delete a schedule

Key scope: schedules:write

Parameters

Field	Type	Description
`scheduleId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 Deleted Deleted
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Schedule not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

Contacts

Contacts with memory: notes and commitments

GET`/v1/contacts`

List contacts

Key scope: contacts:read

Parameters

Field	Type	Description
`limit (query)`	`integer`	Page size (1 to 100, default 20)
`cursor (query)`	`string`	Opaque cursor from `nextCursor` of the previous page
`q (query)`	`string`	Search by name or number

Responses

200 Contacts, newest first ContactList
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/contacts`

Create a contact

Key scope: contacts:write

Parameters

Field	Type	Description
`Idempotency-Key (header)`	`string`	Makes the POST safe to retry: the same key with the same body returns the first response for 24 hours (with `Idempotent-Replayed: true`); the same key with another body returns 409 `idempotency_conflict`.

Request body `CreateContactRequest`

Field	Type	Description
`name` (required)	`string`
`numbers` (required)	`E164[]`
`relationship`	`string`
`language`	`Language`	BCP 47 language tag (language, optional region) Default: "fr".
`formality`	`"tu" \| "vous"`	Default: "vous".
`permissions`	`object`

Responses

201 The contact Contact
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
409 Idempotency key reused Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

GET`/v1/contacts/{contactId}`

Get a contact

Key scope: contacts:read

Parameters

Field	Type	Description
`contactId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 The contact Contact
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Contact not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

PATCH`/v1/contacts/{contactId}`

Update a contact

Key scope: contacts:write

Parameters

Field	Type	Description
`contactId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Request body `UpdateContactRequest`

Field	Type	Description
`name`	`string`
`numbers`	`E164[]`
`relationship`	`string \| null`
`language`	`Language`	BCP 47 language tag (language, optional region)
`formality`	`"tu" \| "vous"`
`permissions`	`object`

Responses

200 The contact Contact
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Contact not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

DELETE`/v1/contacts/{contactId}`

Delete a contact (with its notes and commitments)

Key scope: contacts:write

Parameters

Field	Type	Description
`contactId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 Deleted Deleted
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Contact not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

GET`/v1/contacts/{contactId}/notes`

List a contact's notes

Key scope: contacts:read

Parameters

Field	Type	Description
`contactId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)
`limit (query)`	`integer`	Page size (1 to 100, default 20)
`cursor (query)`	`string`	Opaque cursor from `nextCursor` of the previous page

Responses

200 Notes, newest first ContactNoteList
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Contact not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/contacts/{contactId}/notes`

Add a note to a contact

Key scope: contacts:write

Parameters

Field	Type	Description
`contactId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Request body `CreateContactNoteRequest`

Field	Type	Description
`text` (required)	`string`

Responses

201 The note, `confirmed` ContactNote
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Contact not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

PATCH`/v1/contacts/{contactId}/notes/{noteId}`

Edit, confirm or reject a note

Key scope: contacts:write

Parameters

Field	Type	Description
`contactId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)
`noteId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Request body `UpdateContactNoteRequest`

Field	Type	Description
`text`	`string`
`status`	`"proposed" \| "confirmed" \| "rejected"`

Responses

200 The note ContactNote
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Note not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

DELETE`/v1/contacts/{contactId}/notes/{noteId}`

Delete a note

Key scope: contacts:write

Parameters

Field	Type	Description
`contactId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)
`noteId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 Deleted Deleted
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Note not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

GET`/v1/contacts/{contactId}/commitments`

List a contact's commitments

Key scope: contacts:read

Parameters

Field	Type	Description
`contactId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)
`limit (query)`	`integer`	Page size (1 to 100, default 20)
`cursor (query)`	`string`	Opaque cursor from `nextCursor` of the previous page

Responses

200 Commitments, newest first CommitmentList
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Contact not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/contacts/{contactId}/commitments`

Add a commitment

Key scope: contacts:write

Parameters

Field	Type	Description
`contactId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Request body `CreateCommitmentRequest`

Field	Type	Description
`text` (required)	`string`
`dueAt`	`string (date-time)`	RFC 3339 date-time

Responses

201 The commitment, `open` Commitment
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Contact not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

PATCH`/v1/contacts/{contactId}/commitments/{commitmentId}`

Update or close a commitment

Key scope: contacts:write

Parameters

Field	Type	Description
`contactId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)
`commitmentId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Request body `UpdateCommitmentRequest`

Field	Type	Description
`text`	`string`
`dueAt`	`string (date-time) \| null`
`status`	`"proposed" \| "open" \| "done" \| "canceled"`

Responses

200 The commitment Commitment
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Commitment not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

DELETE`/v1/contacts/{contactId}/commitments/{commitmentId}`

Delete a commitment

Key scope: contacts:write

Parameters

Field	Type	Description
`contactId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)
`commitmentId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 Deleted Deleted
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Commitment not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

GET`/v1/memory/search`

Search the assistant's memory

Key scope: contacts:read

Full-text search across contacts, confirmed and proposed notes, commitments and call summaries. Returns the best matches first.

Parameters

Field	Type	Description
`q (query)` (required)	`string`	Words to look for
`contactId (query)`	`string (uuid)`	Only search this contact's memory
`limit (query)`	`integer`	Maximum hits (1 to 50, default 10)

Responses

200 Matches, best first MemorySearchResult
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

Assistants

GET`/v1/assistants`

List assistants

Key scope: assistants:read

One assistant per user in v1.

Parameters

Field	Type	Description
`limit (query)`	`integer`	Page size (1 to 100, default 20)
`cursor (query)`	`string`	Opaque cursor from `nextCursor` of the previous page

Responses

200 Assistants AssistantList
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

GET`/v1/assistants/{assistantId}`

Get an assistant

Key scope: assistants:read

Parameters

Field	Type	Description
`assistantId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 The assistant Assistant
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Assistant not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

PATCH`/v1/assistants/{assistantId}`

Update an assistant

Key scope: assistants:write

Parameters

Field	Type	Description
`assistantId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Request body `UpdateAssistantRequest`

Field	Type	Description
`name`	`string`
`voice`	`string`
`language`	`Language`	BCP 47 language tag (language, optional region)
`persona`	`string \| null`
`instructions`	`string \| null`
`aiDisclosure`	`boolean`
`recording`	`boolean`
`unknownCallers`	`"take_message" \| "reject"`
`hours`	`AssistantHours \| null`
`websiteUrl`	`string (uri) \| null`

Responses

200 The assistant Assistant
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Assistant not found Error
422 Setting not allowed (AI disclosure cannot be turned off in the cloud) Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

Numbers

GET`/v1/numbers`

List phone numbers

Key scope: numbers:read

Parameters

Field	Type	Description
`limit (query)`	`integer`	Page size (1 to 100, default 20)
`cursor (query)`	`string`	Opaque cursor from `nextCursor` of the previous page

Responses

200 Numbers PhoneNumberList
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/numbers`

Request an own phone number

Key scope: numbers:write

Cloud only. Own numbers need an identity check (KYC) with the carrier; until it is automated this returns 422 `number_provisioning_unavailable` and the request is handled by support.

Parameters

Field	Type	Description
`Idempotency-Key (header)`	`string`	Makes the POST safe to retry: the same key with the same body returns the first response for 24 hours (with `Idempotent-Replayed: true`); the same key with another body returns 409 `idempotency_conflict`.

Request body `ProvisionNumberRequest`

Field	Type	Description
`country`	`"FR"`	ISO 3166-1 alpha-2 country of the number Default: "FR".

Responses

202 Request accepted; the number appears as `pending` Accepted
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
422 Provisioning not available for this account (`policy_violation`) Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

GET`/v1/numbers/{numberId}`

Get a phone number

Key scope: numbers:read

Parameters

Field	Type	Description
`numberId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 The number PhoneNumber
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Number not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

Webhooks

GET`/v1/webhook-endpoints`

List webhook endpoints

Key scope: webhooks:read

Parameters

Field	Type	Description
`limit (query)`	`integer`	Page size (1 to 100, default 20)
`cursor (query)`	`string`	Opaque cursor from `nextCursor` of the previous page

Responses

200 Endpoints WebhookEndpointList
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/webhook-endpoints`

Create a webhook endpoint

Key scope: webhooks:write

Parameters

Field	Type	Description
`Idempotency-Key (header)`	`string`	Makes the POST safe to retry: the same key with the same body returns the first response for 24 hours (with `Idempotent-Replayed: true`); the same key with another body returns 409 `idempotency_conflict`.

Request body `CreateWebhookEndpointRequest`

Field	Type	Description
`url` (required)	`string (uri)`
`description`	`string`
`events` (required)	`WebhookEventType[]`
`enabled`	`boolean`	Default: true.

Responses

201 The endpoint, with its signing secret WebhookEndpointWithSecret
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
409 Idempotency key reused Error
422 The endpoint URL is not a public https URL Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

GET`/v1/webhook-endpoints/{endpointId}`

Get a webhook endpoint

Key scope: webhooks:read

Parameters

Field	Type	Description
`endpointId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 The endpoint WebhookEndpoint
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Endpoint not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

PATCH`/v1/webhook-endpoints/{endpointId}`

Update a webhook endpoint

Key scope: webhooks:write

Parameters

Field	Type	Description
`endpointId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Request body `UpdateWebhookEndpointRequest`

Field	Type	Description
`url`	`string (uri)`
`description`	`string \| null`
`events`	`WebhookEventType[]`
`enabled`	`boolean`

Responses

200 The endpoint WebhookEndpoint
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Endpoint not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

DELETE`/v1/webhook-endpoints/{endpointId}`

Delete a webhook endpoint

Key scope: webhooks:write

Parameters

Field	Type	Description
`endpointId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 Deleted Deleted
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Endpoint not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/webhook-endpoints/{endpointId}/rotate-secret`

Rotate the signing secret

Key scope: webhooks:write

Parameters

Field	Type	Description
`endpointId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 The endpoint, with its new secret WebhookEndpointWithSecret
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Endpoint not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/webhook-endpoints/{endpointId}/test`

Send a test event

Key scope: webhooks:write

Sends one signed sample event to the endpoint and waits for the answer (10 seconds). The delivery is recorded and listed with the others.

Parameters

Field	Type	Description
`endpointId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Request body `TestWebhookEndpointRequest`

Field	Type	Description
`type`	`WebhookEventType`	Event type of the sample payload Default: "call.completed".

Responses

200 The delivery, `succeeded` or `failed` WebhookDelivery
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Endpoint not found Error
422 The endpoint URL is not a public https URL Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

GET`/v1/webhook-endpoints/{endpointId}/deliveries`

List deliveries of an endpoint

Key scope: webhooks:read

Parameters

Field	Type	Description
`endpointId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)
`limit (query)`	`integer`	Page size (1 to 100, default 20)
`cursor (query)`	`string`	Opaque cursor from `nextCursor` of the previous page
`status (query)`	`"pending" \| "succeeded" \| "failed"`

Responses

200 Deliveries, newest first WebhookDeliveryList
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 Endpoint not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

API keys

GET`/v1/api-keys`

List API keys

Key scope: api_keys:read

Parameters

Field	Type	Description
`limit (query)`	`integer`	Page size (1 to 100, default 20)
`cursor (query)`	`string`	Opaque cursor from `nextCursor` of the previous page

Responses

200 Keys (never the secret) ApiKeyList
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

POST`/v1/api-keys`

Create an API key

Key scope: api_keys:write

Parameters

Field	Type	Description
`Idempotency-Key (header)`	`string`	Makes the POST safe to retry: the same key with the same body returns the first response for 24 hours (with `Idempotent-Replayed: true`); the same key with another body returns 409 `idempotency_conflict`.

Request body `CreateApiKeyRequest`

Field	Type	Description
`name` (required)	`string`
`mode`	`"live" \| "test"`	Default: "live".
`scopes`	`ApiScope[]`	Defaults to every scope
`expiresAt`	`string (date-time)`	RFC 3339 date-time

Responses

201 The key; `key` is shown only once CreatedApiKey
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
409 Idempotency key reused Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

DELETE`/v1/api-keys/{apiKeyId}`

Revoke an API key

Key scope: api_keys:write

Parameters

Field	Type	Description
`apiKeyId (path)` (required)	`string (uuid)`	Resource id (UUIDv7)

Responses

200 Revoked Deleted
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
404 API key not found Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

Usage

GET`/v1/usage`

Minutes used in a billing period

Key scope: usage:read

Parameters

Field	Type	Description
`period (query)`	`string`	Month to report, defaults to the current one

Responses

200 Usage of the period Usage
400 Invalid request (validation error) Error
401 Missing or invalid API key Error
403 The API key lacks the required scope Error
429 Rate limited; retry after `Retry-After` seconds Error
500 Internal error Error

Webhook events

The payloads sent to your webhook endpoints. How to receive and verify them is explained in Webhooks.

Allomi API 0.1.0 · generated from openapi.yaml

Webhook events

Payloads POSTed to your webhook endpoints

EVENT`call.started`

A call was answered

Request body `CallStartedEvent`

Field	Type	Description
`id` (required)	`string (uuid)`	Event id; the same event is delivered with the same id on every retry
`type` (required)	`"call.started"`
`apiVersion` (required)	`"2026-11-01"`
`createdAt` (required)	`string (date-time)`	RFC 3339 date-time
`data` (required)	`object`

Responses

200 Any 2xx acknowledges the event

EVENT`call.completed`

A call ended normally

Request body `CallCompletedEvent`

Field	Type	Description
`id` (required)	`string (uuid)`	Event id; the same event is delivered with the same id on every retry
`type` (required)	`"call.completed"`
`apiVersion` (required)	`"2026-11-01"`
`createdAt` (required)	`string (date-time)`	RFC 3339 date-time
`data` (required)	`object`

Responses

200 Any 2xx acknowledges the event

EVENT`call.failed`

A call failed, was not answered or was canceled

Request body `CallFailedEvent`

Field	Type	Description
`id` (required)	`string (uuid)`	Event id; the same event is delivered with the same id on every retry
`type` (required)	`"call.failed"`
`apiVersion` (required)	`"2026-11-01"`
`createdAt` (required)	`string (date-time)`	RFC 3339 date-time
`data` (required)	`object`

Responses

200 Any 2xx acknowledges the event

EVENT`ask.answered`

An ask got its answer

Request body `AskAnsweredEvent`

Field	Type	Description
`id` (required)	`string (uuid)`	Event id; the same event is delivered with the same id on every retry
`type` (required)	`"ask.answered"`
`apiVersion` (required)	`"2026-11-01"`
`createdAt` (required)	`string (date-time)`	RFC 3339 date-time
`data` (required)	`object`

Responses

200 Any 2xx acknowledges the event

EVENT`ask.expired`

An ask expired without answer

Request body `AskExpiredEvent`

Field	Type	Description
`id` (required)	`string (uuid)`	Event id; the same event is delivered with the same id on every retry
`type` (required)	`"ask.expired"`
`apiVersion` (required)	`"2026-11-01"`
`createdAt` (required)	`string (date-time)`	RFC 3339 date-time
`data` (required)	`object`

Responses

200 Any 2xx acknowledges the event

EVENT`contact.created`

A contact was created

Request body `ContactCreatedEvent`

Field	Type	Description
`id` (required)	`string (uuid)`	Event id; the same event is delivered with the same id on every retry
`type` (required)	`"contact.created"`
`apiVersion` (required)	`"2026-11-01"`
`createdAt` (required)	`string (date-time)`	RFC 3339 date-time
`data` (required)	`object`

Responses

200 Any 2xx acknowledges the event

API reference

Authentication

Errors

Pagination

Idempotency

Endpoints

Calls

GET/v1/calls

Parameters

Responses

POST/v1/calls

Parameters

Request body CreateCallRequest

Responses

GET/v1/calls/{callId}

Parameters

Responses

POST/v1/calls/{callId}/hangup

Parameters

Responses

POST/v1/calls/{callId}/say

Parameters

Request body SayInCallRequest

Responses

Asks

GET/v1/asks

Parameters

Responses

POST/v1/asks

Parameters

Request body CreateAskRequest

Responses

GET/v1/asks/{askId}

Parameters

Responses

POST/v1/asks/{askId}/cancel

Parameters

Responses

Schedules

GET/v1/schedules

Parameters

Responses

POST/v1/schedules

Parameters

Request body CreateScheduleRequest

Responses

GET/v1/schedules/{scheduleId}

Parameters

Responses

PATCH/v1/schedules/{scheduleId}

Parameters

Request body UpdateScheduleRequest

Responses

DELETE/v1/schedules/{scheduleId}

Parameters

Responses

Contacts

GET/v1/contacts

Parameters

Responses

POST/v1/contacts

Parameters

Request body CreateContactRequest

Responses

GET/v1/contacts/{contactId}

Parameters

Responses

PATCH/v1/contacts/{contactId}

Parameters

Request body UpdateContactRequest

Responses

DELETE/v1/contacts/{contactId}

Parameters

Responses

GET/v1/contacts/{contactId}/notes

Parameters

Responses

POST/v1/contacts/{contactId}/notes

Parameters

Request body CreateContactNoteRequest

GET`/v1/calls`

POST`/v1/calls`

Request body `CreateCallRequest`

GET`/v1/calls/{callId}`

POST`/v1/calls/{callId}/hangup`

POST`/v1/calls/{callId}/say`

Request body `SayInCallRequest`

GET`/v1/asks`

POST`/v1/asks`

Request body `CreateAskRequest`

GET`/v1/asks/{askId}`

POST`/v1/asks/{askId}/cancel`

GET`/v1/schedules`

POST`/v1/schedules`

Request body `CreateScheduleRequest`

GET`/v1/schedules/{scheduleId}`

PATCH`/v1/schedules/{scheduleId}`

Request body `UpdateScheduleRequest`

DELETE`/v1/schedules/{scheduleId}`

GET`/v1/contacts`

POST`/v1/contacts`

Request body `CreateContactRequest`

GET`/v1/contacts/{contactId}`

PATCH`/v1/contacts/{contactId}`

Request body `UpdateContactRequest`

DELETE`/v1/contacts/{contactId}`

GET`/v1/contacts/{contactId}/notes`

POST`/v1/contacts/{contactId}/notes`

Request body `CreateContactNoteRequest`

PATCH`/v1/contacts/{contactId}/notes/{noteId}`

Request body `UpdateContactNoteRequest`

DELETE`/v1/contacts/{contactId}/notes/{noteId}`

GET`/v1/contacts/{contactId}/commitments`

POST`/v1/contacts/{contactId}/commitments`

Request body `CreateCommitmentRequest`

PATCH`/v1/contacts/{contactId}/commitments/{commitmentId}`

Request body `UpdateCommitmentRequest`

DELETE`/v1/contacts/{contactId}/commitments/{commitmentId}`

GET`/v1/memory/search`

GET`/v1/assistants`

GET`/v1/assistants/{assistantId}`

PATCH`/v1/assistants/{assistantId}`

Request body `UpdateAssistantRequest`

GET`/v1/numbers`

POST`/v1/numbers`

Request body `ProvisionNumberRequest`

GET`/v1/numbers/{numberId}`

GET`/v1/webhook-endpoints`

POST`/v1/webhook-endpoints`

Request body `CreateWebhookEndpointRequest`

GET`/v1/webhook-endpoints/{endpointId}`

PATCH`/v1/webhook-endpoints/{endpointId}`

Request body `UpdateWebhookEndpointRequest`

DELETE`/v1/webhook-endpoints/{endpointId}`

POST`/v1/webhook-endpoints/{endpointId}/rotate-secret`

POST`/v1/webhook-endpoints/{endpointId}/test`