Tickiti

List tickets API

This article and the rest of the API documentation in this section are written for a technical audience — integrators and developers connecting external systems to Tickiti. Familiarity with HTTP, REST, JSON and bearer-token authentication is assumed.

The list endpoint returns the ticket list as Tickiti itself renders it — through a perspective. A perspective is a saved view (its filters, conditions and ordering) configured in the Tickiti interface; the API runs the same query the staff ticket browser does, so the results, ordering and permission filtering match exactly what the acting user would see on screen.

Use it to mirror a Tickiti queue into an external dashboard, to poll for tickets matching a saved filter, or to reconcile state between Tickiti and another system.

Endpoint

POST /api/v1/tickets/query

Headers

  1. Authorization: Bearer YOUR_TOKEN — required. Token must have the tickets:read ability. A tickets:write token also works (write implies read).
  2. Content-Type: application/json — required. No Idempotency-Key is needed (this is a read).

Body

All fields are optional. With an empty body the endpoint returns the built-in All perspective.

  1. perspective_id — the numeric id of the perspective to query. This is the most direct selector.
  2. search_object.search_perspective — alternatively, select a perspective by name (e.g. "All").

Results are always scoped by the permissions of the staff user the token acts as: queues that user cannot see are excluded, and a non-staff owner is restricted to the All perspective. This means a token can never read tickets its owner could not read in the interface.

Example

curl -X POST https://support.sole-provider.example/api/v1/tickets/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "perspective_id": 3
  }'

Successful response

An array of ticket rows, each summarising one ticket. The exact columns follow the perspective, but the core fields are stable:

{
  "ok": true,
  "data": [
    {
      "ticket_id": 1,
      "number": 220009,
      "status": "open",
      "queue": "Returns",
      "priority": "20",
      "subject": "Carbon plate cracked on first marathon",
      "assigned_to_email": "priya.sharma@sole-provider.example",
      "originator_email": "marcus@trailblazers-club.example",
      "created_at": "2026-05-01 09:14:02",
      "updated_at": "2026-05-02 11:30:48"
    }
  ]
}

The list is the same materialised, cached set the ticket browser uses, so it reflects the latest ticket state at query time. Poll it on a sensible interval rather than in a tight loop.

Error responses

  1. 404 not_found — the requested perspective_id or name does not exist.
  2. 401 unauthenticated — bad or missing token.
  3. 403 forbidden — token does not have the tickets:read (or tickets:write) ability.