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 responses to existing tickets, and querying the ticket list. 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/:

  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/query — query the ticket list with criteria.
  4. POST /api/v1/idempotency_key — convenience endpoint that mints a fresh idempotency key for a forthcoming write. No authentication required.

Those are the core ticketing endpoints. 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 API-key minting — are intentionally not exposed.

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. 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 POST /api/v1/tickets and POST /api/v1/tickets/respond.
  2. tickets:read — required for POST /api/v1/tickets/query.

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.

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.

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

Idempotency

The write endpoints (tickets and tickets/respond) 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. 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, licence, storage and more.