Tickets

The Ticket object represents a support conversation with a customer. Tickets belong to an inbox, carry a priority, and contain a thread of messages with optional attachments.

Identifiers

• Ticket ids are prefixed strings such as tkv_4d5e6f... (not UUIDs). Inbox ids start with inb_, tag ids with tag_, message ids with msg_ and customer ids with cus_. User ids (assigned_to, user_id) are UUIDs.
• Every ticket also has a human-readable client_id (e.g. SUP-000123) built from its inbox prefix. Client ids are for display and are not guaranteed to be unique.
• Use the ticket id in the {id} path parameter. Client ids with the SUP- prefix are also accepted on GET/PATCH/DELETE /v1/tickets/{id} and on the /messages and /tags sub-resources. Client ids with any other prefix (inbox prefixes are configurable, default TKT) are treated as ticket ids and return 404. PATCH /v1/tickets/{id}/manage only accepts the ticket id.
• If a SUP- client id matches more than one ticket, GET and PATCH return 404 and DELETE returns 409. Use the ticket id to avoid ambiguity.

Lifecycle

1. open -- new or reopened ticket, awaiting an agent response.
2. pending -- an agent replied; waiting on the customer.
3. review -- the customer replied to a pending ticket; needs agent attention again.
4. resolved -- the issue is resolved.
5. closed -- archived. Resolved and closed tickets reopen (status open) when the customer replies.

Automatic transitions: an outbound reply moves open or review tickets to pending; a customer (inbound) reply moves pending to review, and resolved or closed to open. Internal notes never change the status.

Allowed values

Create a ticketPOST/v1/tickets

Permission: write. Creates a ticket (status open) and its first message, which is stored as an inbound message from the customer. If customer_email does not match an existing customer, the customer is created automatically.

01curl https://api.tickos.dev/v1/tickets \
02  -H 'Authorization: Bearer sk_your_api_key' \
03  -H 'Content-Type: application/json' \
04  -d '{
05    "subject": "Cannot access my account",
06    "message": "Hi, I am unable to log in since yesterday.",
07    "customer_email": "jane@example.com",
08    "customer_name": "Jane Doe",
09    "priority": "high",
10    "assigned_to": "agent@company.com",
11    "metadata": { "source": "api", "plan": "pro" }
12  }'

Returns 201 with { "ticket": {...}, "message": {...}, "attachments": [...] }. The ticket object includes customer { id, name, email }. Fires the ticket.created webhook (no separate message.created event for the first message). If the inbox has an auto-responder, Slack or forwarding configured, those run as well.

List ticketsGET/v1/tickets

Permission: read. Returns { "data": [...], "pagination": { "limit", "offset", "total" } }. Each ticket includes customer { id, name, email }, assigned_to_user { id, email, full_name }, tags [{ id, name, color }], message_count and attachment_count.

Get a ticketGET/v1/tickets/{id}

Permission: read. Returns the bare ticket object (no wrapper) with customer { id, name, email, phone }, assigned_to_user { id, email, full_name }, tags [{ id, name, color }] and an embedded messages array. {id} is the ticket id or a SUP- client id (see Identifiers).

Update a ticketPATCH/v1/tickets/{id}

Permission: write. Updates direct fields; other fields in the body are ignored (400 if none of these is present). Returns the updated ticket object with customer and inbox { id, name, email_address }. Fires the ticket.updated webhook.

Delete a ticketDELETE/v1/tickets/{id}

Permission: admin. Permanently deletes the ticket and its attachments from storage. Returns { "deleted": true, "id": "<id as sent in the path>" }. Fires the ticket.deleted webhook. Returns 409 if a SUP- client id matches more than one ticket (nothing is deleted).

Management actionsPATCH/v1/tickets/{id}/manage

Permission: write. Performs a single operation such as snooze, archive or assign. Send { "action": "...", "data": { ... } }. {id} must be the ticket id (client ids are not accepted). Returns { "ticket": {...}, "action": "...", "message": "..." }, where ticket includes customer and assigned_to_user. Management actions do not fire webhooks.

01curl -X PATCH https://api.tickos.dev/v1/tickets/{id}/manage \
02  -H 'Authorization: Bearer sk_your_api_key' \
03  -H 'Content-Type: application/json' \
04  -d '{ "action": "snooze", "data": { "until": "2025-03-15T09:00:00Z" } }'

An unknown action or missing data returns 400.

Ticket statisticsGET/v1/tickets/stats

Permission: read. Returns counts by status, priority and recent activity (tickets created today, in the last 7 days and this calendar month). Optionally filter by inbox_id. by_status covers open, pending, resolved and closed only (no review count).

01{
02  "total": 284,
03  "unread": 12,
04  "archived": 45,
05  "snoozed": 3,
06  "active": 156,
07  "by_status": { "open": 80, "pending": 40, "resolved": 20, "closed": 16 },
08  "by_priority": { "low": 30, "normal": 100, "medium": 40, "high": 10, "urgent": 2 },
09  "recent_activity": { "today": 15, "this_week": 67, "this_month": 210 }
10}

Agent performance statisticsGET/v1/tickets/agent-stats

Permission: read. Returns per-agent ticket counts by status (agent_id null = unassigned), plus average first response time (first outbound message) and average resolution time in seconds. Query params: start_date, end_date (ISO 8601, filter by ticket creation) and include_timeline=true to add a daily series of resolved tickets per agent.

01{
02  "agents": [
03    {
04      "agent_id": "uuid", "name": "Jane Doe", "email": "jane@acme.com",
05      "total": 120, "open": 10, "pending": 5, "review": 2, "resolved": 80, "closed": 23,
06      "urgent": 3, "unread": 4,
07      "avg_first_response_seconds": 5400, "avg_resolution_seconds": 86400
08    }
09  ],
10  "totals": { "total": 250, "open": 30, "pending": 12, "review": 5, "resolved": 150, "closed": 53, "urgent": 6, "unread": 9 },
11  "timeline": { "days": [ { "date": "2026-07-01", "agents": { "uuid": 12, "unassigned": 3 } } ] }
12}

Tag statisticsGET/v1/tickets/tag-stats

Permission: read. Counts tickets created in the period, grouped by tag, with a breakdown by status. A ticket with several tags counts once in each tag; tags with no tickets in the period are omitted. Tags are sorted by total, descending.

01{
02  "tags": [
03    {
04      "tag_id": "tag_7g8h...", "name": "Billing", "color": "#22c55e", "inbox_id": "inb_2b3c...",
05      "total": 42, "open": 5, "pending": 3, "review": 1, "resolved": 30, "closed": 3
06    }
07  ],
08  "totals": { "tickets": 120, "tagged": 80, "untagged": 40 },
09  "timeline": { "days": [ { "date": "2026-07-01", "tags": { "tag_7g8h...": 4 } } ] }
10}

timeline is only present with include_timeline=true. truncated: true is added when the period contains more tickets than the endpoint processes in one request; narrow the date range in that case.

Compose an email ticketPOST/v1/tickets/compose

Permission: write. Creates a ticket and sends the first message as an outbound email via your verified domain. Only works with email-type inboxes.

Returns 201 with { "success": true, "ticket": { id, client_id, subject, status }, "message_id", "email_status", "attachments_uploaded" }.