Tickiti

Ticketing API overview

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.

Tickiti implements a REST ticketing API for the operations external systems need: creating tickets, posting and correcting responses, querying and reading tickets, and restructuring them — merging, linking, splitting and deleting. This helpdesk API lets you connect your support ticket system to the tools you already run. The API is JSON-only, bearer-token authenticated, and idempotent by design.

Beyond tickets, almost every administrative screen — settings, mail, templates, workflow, reports, supervisor and administration — is available over the same API, so you can automate configuration as well as day-to-day ticketing.

Base URL and conventions

The base URL is your Tickiti install’s public address — for example https://support.sole-trader.example. All current API endpoints sit under /api/v1/. The tickets family covers day-to-day ticketing:

  1. POST /api/v1/tickets — create a new ticket. Supports subject+content, template, or intervention payload shapes.
  2. POST /api/v1/tickets/respond — post a response to an existing ticket.
  3. POST /api/v1/tickets/close — close a ticket, optionally with a response.
  4. POST /api/v1/tickets/participants/add and /participants/remove — add or remove participants; the change is recorded on the thread.
  5. POST /api/v1/tickets/response-update — correct an existing response: replace its body (content), apply find-and-replace edits to the stored body (replace: [{find, replace, all}]), or change its visibility (is_internal) — including on a customer’s response, whose body is never rewritten. Corrections send no notification; notify: true with is_internal: false publishes an internal response and notifies the customer.
  6. POST /api/v1/tickets/response-delete — delete a response.
  7. POST /api/v1/tickets/attachment-upload — upload a file (multipart) to reference from a new ticket or response.
  8. POST /api/v1/tickets/query — query the ticket list with criteria.
  9. POST /api/v1/tickets/show — one ticket with its full response thread.
  10. POST /api/v1/tickets/responses — a ticket’s responses with attachment metadata.
  11. POST /api/v1/tickets/responses/query — responses across every ticket the token can see, by date window, queue and flags.
  12. POST /api/v1/tickets/attachment — download one attachment.
  13. POST /api/v1/tickets/queues and /tickets/teams — the queue names and team keys that ticket fields take.
  14. Ticket operations — tickets/delete, /restore, /merge, /link, /unlink, /links, /response (one response by id), /response-move, /response-copy, /split, /originator-update and /attachment-delete. See Ticket operations API.
  15. Lookups — tickets/staff (staff addresses for participants and assignment), /resolutions (resolution categories) and /search-modes (the query vocabulary).
  16. POST /api/v1/token — what the calling token can do: its abilities per family, its owner’s roles and the plan’s features. Any token may call it.
  17. POST /api/v1/idempotency_key — convenience endpoint that mints a fresh idempotency key for a forthcoming write. No authentication required.

The rest of the interface is exposed family by family under the same /api/v1/<family> convention — see the management APIs (Settings, Mail, Templates, Workflow, Reports, Supervisor, Administration) listed below. A handful of actions that would be dangerous behind a long-lived token — arbitrary scheduled-command creation, licence register/unregister, user deletion and two-factor reset — are intentionally not exposed. API keys can be managed through the Administration API, where a token can only grant abilities it holds itself.

Authentication

Every authenticated API call carries a bearer token in the Authorization header:

Authorization: Bearer YOUR_TICKITI_API_TOKEN

Tokens are minted from Administration → API keys in the admin user-menu dropdown, or through the Administration API. Each token has a fixed set of abilities that gate which endpoints it can call. Abilities follow a <family>:<access> convention, where the family mirrors a section of the Tickiti menu and access is read or write:

  1. tickets:write — required for every endpoint that changes a ticket: create, respond, close, participants, response update and delete, attachment upload, and the ticket operations.
  2. tickets:read — required for the read endpoints: query, show, responses, cross-ticket responses, attachment download, queues, teams, links, a single response, and the lookups.
  3. POST /api/v1/token needs no ability — any token can ask what it can do.

Write implies read: a token holding tickets:write can also call the read (query) endpoint, so you rarely need to grant both. A call always runs with the permissions of the staff user the token acts as, so a token can never do more through the API than that user could do in the interface. Restructuring a ticket — deleting, merging, moving responses — additionally needs Manage on its queue; see Ticket operations API.

Every menu family has the same pair of abilities — settings, mail, templates, workflow, reports, supervisor and administration — each requiring the matching role (staff, admin or superuser). The API keys screen only lists the abilities your own role can grant. A key created or changed through the API can only receive abilities the calling token holds itself, so the API narrows and rotates keys; a wider key is created on the API keys screen.

See Authentication and tokens for how to mint, scope and rotate tokens.

Idempotency

The endpoints that create tickets and post to them (tickets, tickets/respond, tickets/close and tickets/participants/add / remove) require an Idempotency-Key header. Tickiti uses it to guarantee that retrying a request after a network blip never creates a duplicate ticket or response:

  1. Same key + same payload → replay the stored response.
  2. Same key + different payload → conflict (the client got confused).
  3. New key → new operation.

If your client cannot easily generate UUIDs, the /api/v1/idempotency_key endpoint hands one out. See Idempotency for the full semantics.

Response shape

All API responses are JSON with an envelope:

{
  "ok": true,
  "data": { ... }
}

On error, the same envelope with "ok": false and an "error" or "message" field describing what went wrong:

{
  "ok": false,
  "error": "Queue 'Sales' not found."
}

Successful responses use 2xx status codes; client errors (validation, auth, idempotency conflicts) use 4xx; server errors use 5xx.

Quick example

Create a ticket on behalf of a customer with a direct subject and body:

curl -X POST https://support.sole-trader.example/api/v1/tickets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: 7b4f3c2e-9d6a-4f8b-9e7c-2c3a4b5e6f7a" \
  -H "Content-Type: application/json" \
  -d '{
    "originator_email_address": "[email protected]",
    "data": {
      "queue_name": "Sales",
      "subject": "Carbon plate cracked on first marathon",
      "content": "The Vapor Pro 3 plate snapped at mile 14 of Berlin Marathon."
    }
  }'

Successful response:

{
  "ok": true,
  "data": {
    "queue": "Sales",
    "used_template": false,
    "used_intervention": false
  }
}

Where to go next

  1. Authentication and tokens — mint and rotate API tokens, scope abilities.
  2. Create ticket API — full reference for the create endpoint, including the three payload shapes.
  3. Reply to ticket API — post a response to an existing ticket.
  4. List tickets API — query the ticket list by perspective.
  5. Show ticket API, List responses API, Cross-ticket responses API and Download attachment API — read tickets, threads and files.
  6. Ticket operations API — delete and restore, merge, link, move and split responses, change the originator, remove an attachment, correct a response, and the lookups.
  7. Idempotency — key generation, replay and conflict semantics.

Management APIs

The administrative surface, one page per menu family:

  1. Settings API — perspectives, watchlists, hashtags, stock responses.
  2. Mail API — mailboxes, subjects, excluded emails, sent-mail audit.
  3. Templates API — templates and FAQs.
  4. Workflow API — queues, resolution categories, interventions, escalations.
  5. Reports API — analytics (read-only).
  6. Supervisor API — jobs, health, diagnostics.
  7. Administration API — system, branding, users, teams, API keys, licence, storage and more.