Tickiti

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 sending one-off emails through Tickiti’s outbound mailboxes. 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.

Base URL and conventions

The base URL is your Tickiti install’s public address — for example https://support.sole-trader.example. All API endpoints sit under /api/:

  1. POST /api/create_ticket — create a new ticket. Supports subject+content, template, or intervention payload shapes.
  2. POST /api/ticket_respond — post a response to an existing ticket.
  3. POST /api/send_email — send a one-off email through a Tickiti mailbox without creating a ticket.
  4. POST /api/render_template — render a template with data and return the result, without sending it.
  5. POST /api/idempotency_key — convenience endpoint that mints a fresh idempotency key for a forthcoming write. No authentication required.
  6. POST /api/tickiti_api_index — query the ticket list with criteria.

Two simpler alternatives also exist for callers that do not need templates, interventions or idempotency: POST /api/tickets/create and POST /api/tickets/{number}/respond. They accept a flat field set and skip the idempotency requirement. Use them when you genuinely cannot retry on a network failure.

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 and each token has a fixed set of abilities that gate which endpoints it can call:

  1. create-ticket — required for create_ticket and tickets/create.
  2. ticket-respond — required for ticket_respond and tickets/{number}/respond.
  3. send-email — required for send_email and render_template.
  4. ticket-index — required for tickiti_api_index.

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

Idempotency

The write endpoints (create_ticket, ticket_respond, send_email, render_template) require an Idempotency-Key header. Tickiti uses it to guarantee that retrying a request after a network blip never creates a duplicate ticket or sends a duplicate email:

  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/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/create_ticket \n  -H "Authorization: Bearer YOUR_TOKEN" \n  -H "Idempotency-Key: 7b4f3c2e-9d6a-4f8b-9e7c-2c3a4b5e6f7a" \n  -H "Content-Type: application/json" \n  -d '{
    "originator_email_address": "marcus@trailblazers-club.example",
    "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": {
    "ticket_number": 220009,
    "ticket_id": 1,
    "secure_id": "…"
  }
}

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. Send email API — one-off emails that do not create tickets.
  4. Idempotency — key generation, replay and conflict semantics.