DeskAPI reference

Tickets, stats and team

Updated 2026-11-12

Every endpoint on this page is read-only, and read-only keys can call them. Specialists can call all of them except team stats. The shared rules for authentication, rate limits and errors are in Authentication and conventions. IDs and content in the examples are made up.

List assist tickets #

GET/api/tenants/{tenant_id}/tickets

Returns open assist tickets and those closed in the last seven days, up to 500 rows in a single array. Open tickets get priority when selecting rows for the limit.

Parameter Type Required Description
filter string No all (default), pool for unclaimed tickets, mine for tickets you claimed

The main fields of each ticket:

Field Description
ticket_id, conversation_id The ticket and its conversation
public_title The ticket title shown in Desk
status created open, accepted claimed, working in progress, completed resolved, failed couldn't resolve, cancelled
assignee_id Who claimed it; empty when nobody has
task_version The ticket version, usable as expected_task_version when writing a note
due_at Due time
created_at, closed_at When it was opened and closed
curl
curl "$AILO_BASE_URL/api/tenants/demo-shop/tickets?filter=pool" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
200 response (excerpt)
[
  {
    "ticket_id": "t_51",
    "conversation_id": "c_8f21",
    "public_title": "Verify deposit",
    "status": "created",
    "assignee_id": null,
    "task_version": 1,
    "due_at": "2026-11-12T10:30:00Z",
    "created_at": "2026-11-12T09:32:00Z",
    "closed_at": null
  }
]

Search assist tickets #

GET/api/tenants/{tenant_id}/tickets/search

Searches retained assist tickets in the organization, including tickets closed more than seven days ago. Requires tickets.manage and the tickets:read API key scope.

Parameter Type Required Description
query string Yes Ticket title, ticket ID, customer name shown in Desk, or conversation ID
status string No pool, working, waiting, resolved, or attached
mine boolean No true keeps only tickets assigned to the authenticated member. Defaults to false.
cursor string No The previous page's next_cursor. Keep the same query and filters.
limit integer No 1–50, default 50

The response has tickets in the same row format as the list, ordered by the newest ticket activity the caller can see. next_cursor is null on the last page.

Team stats #

GET/api/tenants/{tenant_id}/stats

The same numbers as the Stats page in Desk: resolution rate, how Specialists joined, waiting, first response, assist tickets, satisfaction and more.

It needs the permission to view stats, which only admins and owners have by default; without it you get 403 permission_denied.

Parameter Type Required Description
window string No today, 7d (default) or 30d
from, to string No Custom days as YYYY-MM-DD, both included; give both, at most 90 days, not after today; they replace window
site_id string No One site only; without it, the whole organization

A "day" follows the default time zone of the organization's business hours, or UTC when none is set; timezone in the response names it. The main fields:

Field Description
resolution Resolution rate: ended conversations split into resolved by Ailo, resolved with a Specialist, and unresolved
modes How Specialists joined: assist conversations with an assist ticket, transfer transfers that were picked up, specialist_led times a Specialist started serving on their own
wait Transfer requests, accepted, withdrawn by the customer and expired, with the median wait in seconds
first_response First response
tickets Assist tickets created, claimed, resolved, couldn't resolve and cancelled, with median handling time
rating, ratings_by Customer ratings, split by who was serving when the customer rated
summary, previous, delta This period's headline numbers, the same for the period before, and the change
daily Numbers by day
truncated true when there were too many conversations and only part was counted

There are more fields; the actual response is the reference. A malformed range or one longer than 90 days returns 400 bad_request.

curl
curl "$AILO_BASE_URL/api/tenants/demo-shop/stats?window=30d&site_id=site_th" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"

The team right now #

GET/api/tenants/{tenant_id}/team/now

Returns how many conversations Ailo is serving right now: { "ai_serving": 4 }.

curl
curl "$AILO_BASE_URL/api/tenants/demo-shop/team/now" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"

Confirmation counts #

GET/api/tenants/{tenant_id}/confirmation-counts

Ailo rates its own confidence on every reply. This endpoint counts a period's replies by confidence, and how each one ended: sent directly, approved by a teammate, edited then sent, answered by a teammate, turned into serving, auto-sent on timeout, or discarded.

Parameter Type Required Description
from, to string No ISO times in UTC ending in Z. Without to, this Monday 00:00 UTC; without from, 7 days before to. At most 31 days

Returns total, levels (high, medium and low, each with its count and outcomes) and settings (how many replies would need a teammate's confirmation with the confirmation setting at less, default or more).

curl
curl "$AILO_BASE_URL/api/tenants/demo-shop/confirmation-counts?from=2026-11-02T00:00:00Z&to=2026-11-09T00:00:00Z" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"

Members #

GET/api/tenants/{tenant_id}/agents

Returns the organization's members as an array. Each has fields such as agent_id, display_name, team, presence (online, focus for focus on tickets, away), capacity (how many conversations they can serve at once), open_count (conversations they serve now) and inactive_count (how many of those are inactive).

curl
curl "$AILO_BASE_URL/api/tenants/demo-shop/agents" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
200 response (excerpt)
[
  {
    "agent_id": "a_mia",
    "display_name": "Mia",
    "team": "Payments",
    "presence": "online",
    "capacity": 3,
    "open_count": 2,
    "inactive_count": 0
  }
]

Sites #

GET/api/tenants/{tenant_id}/sites

Returns the organization's sites: { "ok": true, "sites": [ … ] }, each with site_id, name and is_default (whether it is the default site).

curl
curl "$AILO_BASE_URL/api/tenants/demo-shop/sites" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
200 response
{ "ok": true, "sites": [{ "site_id": "site_th", "name": "Thailand", "is_default": true }] }