DeskAPI reference
Authentication and conventions
Desk's open API reads conversations, assist tickets and stats, and writes internal notes on conversations. Desk, the CLI, Orbit and the API all use the same commands with the same permissions. This page covers the rules every endpoint shares; the parameters of each endpoint are in Conversations and Tickets, stats and team.
The full endpoint list can also be read from the service, with no sign-in:
curl "$AILO_BASE_URL/api/openapi.json"
Keys #
The API is called with a personal access key. In Desk, open Settings › My keys and select New key:
- The key is shown only once, when you create it. Save it right away.
- It expires after 90 days by default, 365 days at most; each person can have up to 20 at a time.
- It can be Read-only: a read-only key can call only the read endpoints, and writing a note is refused.
- A key has exactly your own permissions in this organization. When a member is deactivated, all of their keys stop working.
- When you no longer need it, select Revoke key on the same page. Revocation takes effect at once and cannot be undone.
Warning
A key carries your account's permissions. Never put it in front-end code, a public repository or a chat.
Authentication #
Send the key in a header with every request:
Authorization: Bearer <key>
A key is a key ID starting with ak_, a dot, then the secret.
Addresses #
Every endpoint starts with your service address and your organization; paths carry no version number:
$AILO_BASE_URL/api/tenants/{tenant_id}/…
tenant_id is your organization. Anything that belongs to another organization returns 404 not_found, which does not reveal whether it exists.
Source #
The optional header x-ailo-via records where a call came from: api, cli, ui or copilot. Without it the call counts as api; any other value returns 400. The activity log shows the source from this value. Calls made with a key cannot use copilot.
Writes and retries #
Writes are always POST, with this body:
{
"command_id": "c7f0b2d4-1e3a-4c5b-9d8e-7f6a5b4c3d2e",
"idempotency_key": "c7f0b2d4-1e3a-4c5b-9d8e-7f6a5b4c3d2e",
"input": { }
}
command_idandidempotency_keyare both required, 1–200 characters. Generating a UUID for each write works well.- After a network error, retry with the same
command_id,idempotency_keyand content to get the first result back; nothing is written twice. - The same keys with different content return
409 idempotency_key_reused. - Requests with a body need
Content-Type: application/json.
Pagination #
The conversation list returns 50 per page; other lists return everything at once. When there is another page, next_cursor in the response has a value and the x-ailo-next-cursor header carries the same one; pass it back as the cursor parameter for the next page. On the last page next_cursor is null.
Rate limits #
| Scope | Limit |
|---|---|
| Each key | 600 requests a minute |
| All keys in an organization together | 1200 requests a minute |
| Failed authentication from one address | 30 a minute |
Every authenticated response carries three headers, for whichever of the two scopes is tighter:
| Header | Meaning |
|---|---|
X-RateLimit-Limit |
This minute's limit |
X-RateLimit-Remaining |
Requests left |
X-RateLimit-Reset |
When the allowance refills, in Unix seconds |
Past the limit you get 429 rate_limited, and Retry-After gives the number of seconds to wait.
Errors #
On an error the body is { "ok": false, "code": "…" }, sometimes with more fields.
| Status | code |
When |
|---|---|---|
| 400 | bad_request |
A parameter is missing or malformed, or one is not recognized; issues lists each |
| 401 | unauthorized |
No key, or the key is invalid, expired or revoked |
| 403 | permission_denied |
You lack the permission, or a read-only key called a write |
| 404 | not_found |
It does not exist, or belongs to another organization |
| 409 | idempotency_key_reused and others |
The write was refused; code gives the reason |
| 415 | unsupported_media_type |
The body is not JSON |
| 429 | rate_limited |
Too many requests; retry after Retry-After |
| 500 | internal |
The service failed |
401 does not say which of these it was.