Référence de l'API

L'API REST vit sous https://api.allomi.ai/v1 (ou sur ton propre serveur si tu t'auto-héberges). Le fichier OpenAPI 3.1 est packages/contracts/openapi.yaml dans le dépôt, et cette page en est générée. Les descriptions des opérations sont en anglais.

Authentification

Envoie une clé d'API comme jeton « bearer ». Les clés se créent dans l'application (Connecteurs et API) ou avec POST /v1/api-keys, et ont des portées. Chaque opération ci-dessous indique celle qu'elle exige.

Authorization: Bearer alm_live_…

Erreurs

Toute réponse hors 2xx a le même corps, et un en-tête Request-Id à citer au support.

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

Pagination

Les endpoints de liste renvoient { "data": [...], "nextCursor": "…" | null }, du plus récent au plus ancien. Passe cursor avec le nextCursor précédent pour la page suivante, et limit (1 à 100, 20 par défaut) pour sa taille.

Idempotence

Les POST qui créent une ressource acceptent un en-tête Idempotency-Key. La même clé avec le même corps renvoie la première réponse pendant 24 heures (avec Idempotent-Replayed: true). La même clé avec un autre corps renvoie 409 idempotency_conflict.

Endpoints

Allomi API 0.1.0 · généré depuis openapi.yaml (en anglais)

Calls

GET`/v1/calls`

List calls

Portée de la clé: calls:read

Paramètres

Champ	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)

Réponses

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

Portée de la clé: 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}`.

Paramètres

Champ	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`.

Corps de la requête `CreateCallRequest`

Champ	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` (obligatoire)	`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.

Réponses

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)

Portée de la clé: calls:read

Paramètres

Champ	Type	Description
`callId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: calls:write

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

Paramètres

Champ	Type	Description
`callId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: calls:write

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

Paramètres

Champ	Type	Description
`callId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Corps de la requête `SayInCallRequest`

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

Réponses

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

Portée de la clé: asks:read

Paramètres

Champ	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"`

Réponses

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)

Portée de la clé: 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}`.

Paramètres

Champ	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`.

Corps de la requête `CreateAskRequest`

Réponses

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

Portée de la clé: asks:read

Paramètres

Champ	Type	Description
`askId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: asks:write

Paramètres

Champ	Type	Description
`askId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: schedules:read

Paramètres

Champ	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`

Réponses

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)

Portée de la clé: schedules:write

Paramètres

Champ	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`.

Corps de la requête `CreateScheduleRequest`

Champ	Type	Description
`contactId`	`string (uuid)`	Omit to call the owner
`prompt` (obligatoire)	`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.

Réponses

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

Portée de la clé: schedules:read

Paramètres

Champ	Type	Description
`scheduleId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: schedules:write

Paramètres

Champ	Type	Description
`scheduleId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Corps de la requête `UpdateScheduleRequest`

Champ	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.

Réponses

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

Portée de la clé: schedules:write

Paramètres

Champ	Type	Description
`scheduleId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: contacts:read

Paramètres

Champ	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

Réponses

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

Portée de la clé: contacts:write

Paramètres

Champ	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`.

Corps de la requête `CreateContactRequest`

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

Réponses

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

Portée de la clé: contacts:read

Paramètres

Champ	Type	Description
`contactId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: contacts:write

Paramètres

Champ	Type	Description
`contactId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Corps de la requête `UpdateContactRequest`

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

Réponses

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)

Portée de la clé: contacts:write

Paramètres

Champ	Type	Description
`contactId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: contacts:read

Paramètres

Champ	Type	Description
`contactId (path)` (obligatoire)	`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

Réponses

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

Portée de la clé: contacts:write

Paramètres

Champ	Type	Description
`contactId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Corps de la requête `CreateContactNoteRequest`

Champ	Type	Description
`text` (obligatoire)	`string`

Réponses

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

Portée de la clé: contacts:write

Paramètres

Champ	Type	Description
`contactId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)
`noteId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Corps de la requête `UpdateContactNoteRequest`

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

Réponses

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

Portée de la clé: contacts:write

Paramètres

Champ	Type	Description
`contactId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)
`noteId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: contacts:read

Paramètres

Champ	Type	Description
`contactId (path)` (obligatoire)	`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

Réponses

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

Portée de la clé: contacts:write

Paramètres

Champ	Type	Description
`contactId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Corps de la requête `CreateCommitmentRequest`

Champ	Type	Description
`text` (obligatoire)	`string`
`dueAt`	`string (date-time)`	RFC 3339 date-time

Réponses

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

Portée de la clé: contacts:write

Paramètres

Champ	Type	Description
`contactId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)
`commitmentId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Corps de la requête `UpdateCommitmentRequest`

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

Réponses

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

Portée de la clé: contacts:write

Paramètres

Champ	Type	Description
`contactId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)
`commitmentId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: contacts:read

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

Paramètres

Champ	Type	Description
`q (query)` (obligatoire)	`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)

Réponses

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

Portée de la clé: assistants:read

One assistant per user in v1.

Paramètres

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

Réponses

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

Portée de la clé: assistants:read

Paramètres

Champ	Type	Description
`assistantId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: assistants:write

Paramètres

Champ	Type	Description
`assistantId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Corps de la requête `UpdateAssistantRequest`

Champ	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`

Réponses

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

Portée de la clé: numbers:read

Paramètres

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

Réponses

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

Portée de la clé: 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.

Paramètres

Champ	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`.

Corps de la requête `ProvisionNumberRequest`

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

Réponses

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

Portée de la clé: numbers:read

Paramètres

Champ	Type	Description
`numberId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: webhooks:read

Paramètres

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

Réponses

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

Portée de la clé: webhooks:write

Paramètres

Champ	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`.

Corps de la requête `CreateWebhookEndpointRequest`

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

Réponses

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

Portée de la clé: webhooks:read

Paramètres

Champ	Type	Description
`endpointId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: webhooks:write

Paramètres

Champ	Type	Description
`endpointId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Corps de la requête `UpdateWebhookEndpointRequest`

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

Réponses

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

Portée de la clé: webhooks:write

Paramètres

Champ	Type	Description
`endpointId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: webhooks:write

Paramètres

Champ	Type	Description
`endpointId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: 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.

Paramètres

Champ	Type	Description
`endpointId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Corps de la requête `TestWebhookEndpointRequest`

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

Réponses

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

Portée de la clé: webhooks:read

Paramètres

Champ	Type	Description
`endpointId (path)` (obligatoire)	`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"`

Réponses

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

Portée de la clé: api_keys:read

Paramètres

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

Réponses

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

Portée de la clé: api_keys:write

Paramètres

Champ	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`.

Corps de la requête `CreateApiKeyRequest`

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

Réponses

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

Portée de la clé: api_keys:write

Paramètres

Champ	Type	Description
`apiKeyId (path)` (obligatoire)	`string (uuid)`	Resource id (UUIDv7)

Réponses

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

Portée de la clé: usage:read

Paramètres

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

Réponses

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

Événements webhook

Les charges envoyées à tes endpoints webhook. La réception et la vérification sont expliquées dans Webhooks.

Allomi API 0.1.0 · généré depuis openapi.yaml (en anglais)

Webhook events

Payloads POSTed to your webhook endpoints

EVENT`call.started`

A call was answered

Corps de la requête `CallStartedEvent`

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

Réponses

200 Any 2xx acknowledges the event

EVENT`call.completed`

A call ended normally

Corps de la requête `CallCompletedEvent`

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

Réponses

200 Any 2xx acknowledges the event

EVENT`call.failed`

A call failed, was not answered or was canceled

Corps de la requête `CallFailedEvent`

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

Réponses

200 Any 2xx acknowledges the event

EVENT`ask.answered`

An ask got its answer

Corps de la requête `AskAnsweredEvent`

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

Réponses

200 Any 2xx acknowledges the event

EVENT`ask.expired`

An ask expired without answer

Corps de la requête `AskExpiredEvent`

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

Réponses

200 Any 2xx acknowledges the event

EVENT`contact.created`

A contact was created

Corps de la requête `ContactCreatedEvent`

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

Réponses

200 Any 2xx acknowledges the event

Référence de l'API

Authentification

Erreurs

Pagination

Idempotence

Endpoints

Calls

GET/v1/calls

Paramètres

Réponses

POST/v1/calls

Paramètres

Corps de la requête CreateCallRequest

Réponses

GET/v1/calls/{callId}

Paramètres

Réponses

POST/v1/calls/{callId}/hangup

Paramètres

Réponses

POST/v1/calls/{callId}/say

Paramètres

Corps de la requête SayInCallRequest

Réponses

Asks

GET/v1/asks

Paramètres

Réponses

POST/v1/asks

Paramètres

Corps de la requête CreateAskRequest

Réponses

GET/v1/asks/{askId}

Paramètres

Réponses

POST/v1/asks/{askId}/cancel

Paramètres

Réponses

Schedules

GET/v1/schedules

Paramètres

Réponses

POST/v1/schedules

Paramètres

Corps de la requête CreateScheduleRequest

Réponses

GET/v1/schedules/{scheduleId}

Paramètres

Réponses

PATCH/v1/schedules/{scheduleId}

Paramètres

Corps de la requête UpdateScheduleRequest

Réponses

DELETE/v1/schedules/{scheduleId}

Paramètres

Réponses

Contacts

GET/v1/contacts

Paramètres

Réponses

POST/v1/contacts

Paramètres

Corps de la requête CreateContactRequest

Réponses

GET/v1/contacts/{contactId}

Paramètres

Réponses

PATCH/v1/contacts/{contactId}

Paramètres

Corps de la requête UpdateContactRequest

Réponses

DELETE/v1/contacts/{contactId}

Paramètres

Réponses

GET/v1/contacts/{contactId}/notes

Paramètres

Réponses

POST/v1/contacts/{contactId}/notes

Paramètres

Corps de la requête CreateContactNoteRequest

GET`/v1/calls`

POST`/v1/calls`

Corps de la requête `CreateCallRequest`

GET`/v1/calls/{callId}`

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

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

Corps de la requête `SayInCallRequest`

GET`/v1/asks`

POST`/v1/asks`

Corps de la requête `CreateAskRequest`

GET`/v1/asks/{askId}`

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

GET`/v1/schedules`

POST`/v1/schedules`

Corps de la requête `CreateScheduleRequest`

GET`/v1/schedules/{scheduleId}`

PATCH`/v1/schedules/{scheduleId}`

Corps de la requête `UpdateScheduleRequest`

DELETE`/v1/schedules/{scheduleId}`

GET`/v1/contacts`

POST`/v1/contacts`

Corps de la requête `CreateContactRequest`

GET`/v1/contacts/{contactId}`

PATCH`/v1/contacts/{contactId}`

Corps de la requête `UpdateContactRequest`

DELETE`/v1/contacts/{contactId}`

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

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

Corps de la requête `CreateContactNoteRequest`

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

Corps de la requête `UpdateContactNoteRequest`

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

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

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

Corps de la requête `CreateCommitmentRequest`

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

Corps de la requête `UpdateCommitmentRequest`

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

GET`/v1/memory/search`

GET`/v1/assistants`

GET`/v1/assistants/{assistantId}`

PATCH`/v1/assistants/{assistantId}`

Corps de la requête `UpdateAssistantRequest`

GET`/v1/numbers`

POST`/v1/numbers`

Corps de la requête `ProvisionNumberRequest`

GET`/v1/numbers/{numberId}`

GET`/v1/webhook-endpoints`

POST`/v1/webhook-endpoints`

Corps de la requête `CreateWebhookEndpointRequest`

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

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

Corps de la requête `UpdateWebhookEndpointRequest`

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

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

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