DeskAPI reference

Authentication and conventions

Updated 2026-11-12

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:

Shell
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:

Text
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:

Text
$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:

JSON
{
  "command_id": "c7f0b2d4-1e3a-4c5b-9d8e-7f6a5b4c3d2e",
  "idempotency_key": "c7f0b2d4-1e3a-4c5b-9d8e-7f6a5b4c3d2e",
  "input": { }
}
  • command_id and idempotency_key are both required, 1–200 characters. Generating a UUID for each write works well.
  • After a network error, retry with the same command_id, idempotency_key and 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.