DeskAPI reference
Tickets, stats and team
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 "$AILO_BASE_URL/api/tenants/demo-shop/tickets?filter=pool" \
-H "Authorization: Bearer $AILO_ACCESS_KEY"
[
{
"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 "$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 "$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 "$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 "$AILO_BASE_URL/api/tenants/demo-shop/agents" \
-H "Authorization: Bearer $AILO_ACCESS_KEY"
[
{
"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 "$AILO_BASE_URL/api/tenants/demo-shop/sites" \
-H "Authorization: Bearer $AILO_ACCESS_KEY"
{ "ok": true, "sites": [{ "site_id": "site_th", "name": "Thailand", "is_default": true }] }