Ticket operations 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 ticket operations endpoints restructure tickets the way the ticket page does: delete and restore, merge, link, move or copy responses between tickets, split responses off into a new ticket, change the originator, and remove a single attachment. Alongside them sit the lookups a ticket-scoped token needs — staff addresses, resolution categories, the search vocabulary — and an endpoint that tells any token what it can do. They work on tasks as they do on tickets: a ticket’s messages and a task’s notes are both responses here.

Every write runs through the same code as the ticket page, so the result is exactly what a staff member would get doing the same thing by hand, including the audit lines on the ticket thread. All endpoints are POST, take and return JSON, and use the response envelope described in the API overview.

Endpoints

Method & pathAbilityPurpose
POST /api/v1/tickets/deletetickets:writeDelete tickets by number or by sender
POST /api/v1/tickets/restoretickets:writeRestore a deleted ticket
POST /api/v1/tickets/mergetickets:writeMerge two tickets
POST /api/v1/tickets/linktickets:writeLink tickets
POST /api/v1/tickets/unlinktickets:writeRemove a link
POST /api/v1/tickets/linkstickets:readList a ticket’s linked tickets
POST /api/v1/tickets/responsetickets:readRead one response by id
POST /api/v1/tickets/response-movetickets:writeMove responses to another ticket
POST /api/v1/tickets/response-copytickets:writeCopy responses to another ticket
POST /api/v1/tickets/splittickets:writeSplit responses off into a new linked ticket
POST /api/v1/tickets/originator-updatetickets:writeChange who raised the ticket
POST /api/v1/tickets/attachment-deletetickets:writeRemove one attachment
POST /api/v1/tickets/response-updatetickets:writeEdit a response, change its visibility, or publish it
POST /api/v1/tickets/response-deletetickets:writeDelete a response
POST /api/v1/tickets/stafftickets:readStaff who can be participants or assignees
POST /api/v1/tickets/resolutionstickets:readResolution categories
POST /api/v1/tickets/search-modestickets:readThe ticket-query search vocabulary
POST /api/v1/tokenany tokenWhat the calling token can do

Write implies read: a token holding tickets:write can call every endpoint above. None of these endpoints takes an Idempotency-Key.

Who may do what

A call runs as the token’s owner, and every ticket a request touches is checked against that owner with the same rules as the ticket page. There are two levels:

  1. Seeing a ticket — the owner is its assignee (directly, or as a member of the assigned team), one of its participants, or has access to its queue. Linking, listing links, reading a response and copying responses off a ticket need this.
  2. Managing a ticket — the owner can see the ticket and is an admin or holds Manage on its queue (see Queue permissions). Deleting, restoring, merging, moving responses, receiving moved or copied responses, changing the originator and removing an attachment need this.

Integration identities act on tickets in every queue without these per-ticket checks: the System user (the default owner on Administration → API keys), accounts marked API user, and on a self-hosted installation sysadmins and superusers. On a site hosted by Tickiti, an administrator’s own key is not one: give an integration an API user account. POST /api/v1/token reports which kind of owner a token has.

Every check runs before anything is written. If any ticket in a request fails, the whole request is refused with 403 forbidden and nothing changes.

Tickets and tasks

An entry is a ticket or a task for good, and these endpoints keep the two apart. A call that breaks one of these rules is refused with a 422 and a message saying why:

  1. Same kind only. Merging, and moving or copying responses, work only between two tickets or two tasks: #220009 is a ticket and #220077 is a task: merging works only between two tickets or two tasks. A split makes an entry of the source’s kind. The one way from a ticket to a task is Create task from ticket on the ticket page, which makes a new task linked to the ticket.
  2. Queues. Any queue holds tickets and tasks alike, but nothing is put in Drafts, so a split into Drafts is refused.
  3. Only staff on a task. A task’s originator and participants are members of staff: changing a task’s originator to anyone else is refused, for example Only staff can be participants on a task: [email protected] is not staff.
  4. The task description. A task’s first note is its description (initial_response_id and is_task_description in Show ticket). It can’t be deleted, moved or split off the task, unpinned or emptied: A task's description can't be moved off its task (#220031). Copying it leaves it where it is.
  5. The last message or note. Every ticket or task keeps at least one: deleting its last one, or moving or splitting it away, is refused — Moving it would leave #220009 with no messages: a ticket always keeps at least one message.
  6. Public notes. A note on a task is never made public.

Delete tickets

POST /api/v1/tickets/delete

Deletes tickets as Delete in the ticket list does: each ticket’s responses are deleted with it, the ticket leaves every ticket list, and it can be brought back with tickets/restore. Select tickets by number, or every ticket raised by one address — for example, clearing out a run of newsletters from one sender in a single call.

Body:

  1. ticket_numbers — array of ticket numbers, up to 1,000.
  2. originator_email — select the tickets raised by this address. Give ticket_numbers, originator_email, or both (a ticket then has to match both).
  3. queue — optional queue name; only tickets in that queue are selected.
  4. dry_run — boolean. When true, Tickiti returns the tickets the call would delete and deletes nothing.

The operation is all-or-nothing. A selection of more than 1,000 tickets is refused (422, narrow it); every number in ticket_numbers must exist (404 names the missing ones); the owner must manage every selected ticket (403); and a ticket locked by another staff member stops the whole batch (422 refused). Permission checks apply to a dry run too, so a dry run that succeeds predicts the real call.

curl -X POST https://support.sole-provider.example/api/v1/tickets/delete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "originator_email": "[email protected]", "queue": "Inbox", "dry_run": true }'
{
  "ok": true,
  "data": {
    "dry_run": true,
    "count": 2,
    "tickets": [
      { "ticket_number": "220141", "subject": "Weekend flash sale", "status": "open", "queue": "Inbox" },
      { "ticket_number": "220158", "subject": "Last chance: 40% off", "status": "open", "queue": "Inbox" }
    ]
  }
}

Without dry_run the response is { "deleted": 2, "tickets": [ ... ], "restorable": true }, listing the same fields for each ticket deleted.

Restore a ticket

POST /api/v1/tickets/restore

Body: ticket_number. Restores a deleted ticket together with the responses that were deleted with it; a response that was deleted on its own beforehand stays deleted. The thread records who restored the ticket. The owner must manage the ticket. The responses come back as they were, not as new messages: they start no automations, SLA timing, satisfaction survey, Axial reply or out-of-office reply.

Response: { "ticket_number": "220141", "status": "open" }. A ticket that is not deleted is refused (422 refused), and so is a ticket that was merged into another — its responses live on the surviving ticket. A ticket or task comes back into the queue it was in, so a restore is also refused when that queue has since been deleted: Ticket #220141 can't be restored: the queue it was in no longer exists.

From an Axial agent task, a restore that would bring back public responses the ticket’s customer can read is not made: it waits for a person’s approval as a card on the task’s ticket, and the call returns 202 with status: "awaiting_approval" and the card’s approval_id. A task that is not on a ticket has nowhere to put the card, so its restore is refused with 403, and a reply task only reads, so its restore is always refused with 403.

Merge two tickets

POST /api/v1/tickets/merge

Body: ticket_number and other_ticket_number (two different tickets, or two different tasks, in either order). The owner must manage both. A ticket and a task are never merged (422 refused).

  1. The older ticket (by creation time) survives, whichever order you give them in.
  2. The newer ticket’s participants are added to the survivor, and each of its responses is copied across with its attachments. The copies are not new messages: they start no automations, SLA timing, satisfaction survey, Axial reply or out-of-office reply. If the survivor had no first response yet, its first response becomes the earliest public staff reply among its responses, the copies included.
  3. The newer ticket is marked as merged into the survivor and deleted. The survivor’s thread records the merge.
  4. When two tasks merge, the surviving task keeps its own description, and the other task’s notes, its description among them, arrive as notes on it. A surviving task with no description takes its first note as one.
  5. An on-hold survivor is reopened, its on-hold timer cleared, and its assignee notified (each member, when it is assigned to a team).

Response: { "surviving_ticket_number": "220009", "merged_ticket_number": "220077" }.

From an Axial agent task, a merge that would add someone outside your team to the surviving ticket, or show the other ticket’s public responses to the survivor’s customer, is not made: it waits for a person’s approval as a card on the task’s ticket, and the call returns 202 with status: "awaiting_approval" and the card’s approval_id. A task that is not on a ticket puts the card on the ticket named in ticket_number. A reply task only reads, so its merge is always refused with 403.

Link, unlink and list links

POST /api/v1/tickets/link
POST /api/v1/tickets/unlink
POST /api/v1/tickets/links

These manage the ticket page’s Linked panel (see Ticket links). Each takes the ticket as ticket_number or ticket_id.

  1. link — linked_ticket_numbers: array of 1 to 100 ticket numbers to link to the ticket. Links are two-way, and a ticket can be linked to a task; linking a pair that is already linked changes nothing. The owner must be able to see the ticket and every ticket being linked to it. Response: newly_linked (how many links were added) and linked_tickets.
  2. unlink — linked_ticket_number: the ticket to unlink. The owner must be able to see both the ticket named in ticket_number / ticket_id and the linked ticket (403 otherwise), as on the ticket page. Clone links — made by cloning or by tickets/split — are permanent, and unlinking two tickets that are not linked is refused (422 refused in both cases). Response: linked_tickets.
  3. links — reads the panel (tickets:read, staff account). Response: ticket_number and linked_tickets.

Each entry in linked_tickets carries link_id, ticket_id, ticket_number, subject, status, link_type (manual or clone) and clone_direction — to when this ticket is the source of the clone, from when it is the clone, null for a manual link. Deleted tickets are left out, as in the panel.

Read one response

POST /api/v1/tickets/response

Reads a single response by its id alone, together with the ticket it belongs to — useful when a webhook, report or search hands you a response id. Ability tickets:read; the owner must be a staff account (or an integration identity) that can see the ticket.

  1. response_id — required, integer.
  2. max_body_chars — optional; truncates html and plain_text to this many characters.
  3. include — optional; original_html (the email as it arrived) and reply_text (the writer’s words without the quoted history). The reply also carries mail_auth: pass or fail for an email response, api for one posted through the API in the sender’s name, so nothing checked the address, otherwise null. See Responses and tags API.

Deleted responses, and responses on deleted tickets, are returned too, with deleted set.

{
  "ok": true,
  "data": {
    "response_id": "90412",
    "ticket_id": "1187",
    "ticket_number": "220009",
    "ticket_subject": "Carbon plate cracked on first marathon",
    "is_internal": false,
    "staff_response": true,
    "created_by_email": "[email protected]",
    "created_at": "2026-09-14T09:12:44+00:00",
    "updated_at": "2026-09-14T09:12:44+00:00",
    "deleted": false,
    "audit": null,
    "other_changes": null,
    "html": "<p>A replacement pair is on its way.</p>",
    "plain_text": "A replacement pair is on its way.",
    "attachments": []
  }
}

audit lists the ticket changes the response recorded (status, priority, assignee, queue, participants, subject and so on), or is null. Attachments have the same shape as in the List responses API.

Move and copy responses

POST /api/v1/tickets/response-move
POST /api/v1/tickets/response-copy

Body: response_ids (array of 1 to 500 response ids, from one ticket or several) and target_ticket_number. Each response is re-created on the target with its author, internal/public flag, recorded changes, timestamps and attachments; a move then deletes the original. The target and each source ticket get a line on their thread recording how many responses were moved or copied, between which tickets, and by whom.

Permissions: the owner must manage the target. A move also needs management of every source ticket, since it takes responses away; a copy only needs sight of them.

Response: moved or copied (the count), target_ticket_number, and new_response_ids in the order the ids were given. An unknown response id returns 404; a response already on the target ticket is refused (422 refused). Responses move or copy only between two tickets or two tasks, and a move can’t take a task’s description off it, nor leave a source with no message or note (422 refused; see Tickets and tasks).

The copies are not new messages on the target: they start no automations, SLA timing, satisfaction survey, Axial reply or out-of-office reply, and a staff reply copied onto it is not the target ticket’s first response.

From an Axial agent task, a move or copy that would put a public response where someone outside your team could not already read it is not made: it waits for a person’s approval as a card on the task’s ticket, and the call returns 202 with status: "awaiting_approval" and the card’s approval_id. A task that is not on a ticket puts the card on the target ticket. A move or copy between two tickets of the same customer goes straight through. A reply task only reads, so its move or copy is always refused with 403.

Split responses into a new ticket

POST /api/v1/tickets/split

Moves (or copies) responses off one ticket onto a new ticket, linked to the original as its clone — the way to separate a second conversation that arrived on an existing ticket.

  1. response_ids — array of 1 to 500 response ids, all from the same ticket.
  2. subject — the new ticket’s subject (up to 255 characters).
  3. queue — optional queue name for the new ticket; defaults to the source ticket’s queue. The new entry is the source’s kind — a ticket splits into a ticket and a task into a task — whatever its queue, which can’t be Drafts: The new ticket can't be put in Drafts: choose the queue it goes to. (422 refused).
  4. copy — boolean, default false. False moves the responses; true copies them and leaves the source untouched.

The new ticket opens with the source ticket’s originator, assignee, priority and participants, and both threads record the transfer as for response-move. Its responses are copies, so they start no automations, satisfaction survey, Axial reply or out-of-office reply, but the new ticket is given its SLA policy as any new ticket is (a task has none), and its first response is the earliest public staff reply it was split off with. Permissions follow move and copy: splitting with a move needs management of the source ticket, splitting with copy needs sight of it.

A move can’t take a task’s description, or the source’s only message or note, so splitting off everything a ticket holds is refused (422 refused); split with copy instead. A task split off with a move or a copy takes the earliest of its notes as its description.

Response: { "new_ticket_number": "220212", "source_ticket_number": "220009", "queue": "Support", "moved": 3 } (copied in place of moved for a copy).

Change the originator

POST /api/v1/tickets/originator-update

Body: the ticket (ticket_number or ticket_id) and originator_email. Use it when a ticket was raised under the wrong one of a person’s addresses. The owner must manage the ticket.

The new address becomes the originator and a participant. The previous originator stays a participant — remove them with POST /api/v1/tickets/participants/remove if they should go. The thread records the change. Giving the address that is already the originator is refused (422 refused), and so is anyone who is not a member of staff on a task.

From an Axial agent task, a change to an originator who is not a member of staff and is not already on the ticket is not made, since the new originator would be sent every public reply from then on and could open the whole history: it waits for a person’s approval as a card on the task’s ticket, and the call returns 202 with status: "awaiting_approval" and the card’s approval_id. A task that is not on a ticket puts the card on the ticket named in ticket_number; named only by ticket_id, it is refused with 403. A reply task only reads, so its change is always refused with 403. When Axial makes the same change itself while it works on a ticket, it is put to a person as a card in the same way.

The Axial checks on restore, merge, move, copy and originator changes read ticket numbers and ids as the endpoints do: spaces around them, including no-break and zero-width spaces, are ignored, so a number written with one is checked like any other.

Response: ticket_number, previous, originator_email and audit_response_id (the response that records the change).

Delete an attachment

POST /api/v1/tickets/attachment-delete

Removes one attachment from a response — above all, a malicious file that should not stay on the ticket. The owner must manage the ticket.

  1. The ticket, as ticket_number or ticket_id.
  2. response_attachment_id — the attachment’s id, as returned by the Show ticket and List responses APIs. It must belong to a response on that ticket, or the call returns 404.
  3. reason — optional, up to 500 characters.

Tickiti stores attachment content by its SHA-256 hash, so the same file can sit on several responses and drafts. The attachment is removed from the response, and the stored file is deleted as well when nothing else uses it. The response keeps a line recording the file name, its SHA-256, who removed it, when (UTC) and the reason, so the record of what arrived outlives the file.

Response: { "deleted": "invoice.pdf.exe", "sha256": "9f2c…", "file_purged": true }. file_purged is false when the stored file is still in use elsewhere.

Edit or delete a response

POST /api/v1/tickets/response-update
POST /api/v1/tickets/response-delete

response-update corrects an existing response in place. Body: response_id plus at least one of:

  1. content — the whole new body (HTML; inline base64 images are stored as attachments, as on reply).
  2. replace — an array of { "find": "…", "replace": "…", "all": false } edits applied in order to the stored body. Each find must occur in the body, and must occur exactly once unless all is true. Every edit is checked before anything is written. Give content or replace, not both.
  3. is_internal — boolean; changes the response’s visibility between internal and public. A note on a task stays internal: is_internal: false on one is refused with 422 validation_failed and errors.is_internal: A note on a task can't be made public.
  4. notify — boolean, used with is_internal: false on an internal response: the response is published, signed as it would have been had it been posted public, and every participant who is not staff is notified, as Change to public does on the ticket page.

A correction is silent: no notification is sent unless notify is true. Body edits apply to staff responses; a customer’s response is never rewritten, though its visibility can be changed with is_internal — for example, a customer reply that was filed internal. Making a public response internal takes it out of the customer’s view of the ticket; notifications already sent for it stay sent. The response records each edit and each visibility change with who made it and when. A task’s description can’t be edited to nothing: an empty content or replace result is refused with 422 validation_failed (A task's description can't be empty.). Response: response_id, is_internal, other_changes and notified.

response-delete takes response_id and deletes the response. Response: { "response_id": "90412" }. It is refused with 422 refused for a task’s description (A task's description can't be deleted.) and for the last message or note on a ticket or task (This is the only message left on #220009, so it can't be deleted.).

Both endpoints are open to the response’s author, an admin, or a manager of the ticket’s queue, on a ticket they can see; integration identities are exempt as above.

Lookups

POST /api/v1/tickets/staff (tickets:read) — the staff who can be participants or assignees. Optional search matches part of a name or email address. Each entry carries id, name, email and teams (the team keys, such as team:4, that assigned_to_email accepts); the response also gives count. Participants and assignment take email addresses, so look them up here rather than guessing.

POST /api/v1/tickets/resolutions (tickets:read) — the resolution categories a ticket can be closed with, in display order: { "resolution_categories": [ { "id": "3", "name": "Fixed", "selectable": true } ] }.

POST /api/v1/tickets/search-modes (tickets:read) — the search vocabulary of the List tickets API: modes maps each mode to a description, and rules explains how criteria and tokens combine.

POST /api/v1/token (any token, no ability needed) — what the calling token can do, so a client can tell a missing ability from a missing role or plan feature. The response holds:

  1. token — name, abilities, wildcard, expires_at, last_used_at, allowed_ip.
  2. owner — email, name, the role flags is_staff, is_admin, is_sysadmin, is_superuser, is_api_user, and ticket_access_exempt (true for an integration identity).
  3. families — one entry per ability family: read and write (whether the token holds them, write implying read), extras (any further ability of the family, each true or false — such as tickets:customer_impersonation or axial-chat:approve; an Axial chat one also counts as read, since the family’s read endpoints accept it, and tickets:customer_impersonation does not), required_role, and role_ok (whether the owner holds that role; an API user account counts as staff).
  4. plan — the instance’s plan features, each true or false.

Error responses

  1. 422 validation_failed — a missing or malformed field; errors lists them by field.
  2. 422 refused — the operation does not apply to this ticket as it stands (locked, not deleted, merged, a clone link, already the originator, already on the target, a ticket and a task together, Drafts, someone who is not staff on a task, a task’s description, the last message or note); message says why.
  3. 404 not_found — an unknown ticket, response or attachment; resource and message say which.
  4. 403 forbidden — the token lacks the ability, or its owner cannot see or manage a ticket involved.
  5. 401 unauthenticated — bad or missing token.

See Authentication and tokens for abilities, and the API overview for the shared conventions.