Personal ticket state 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.
Some of what Tickiti keeps about a ticket belongs to each member of staff alone: whether they have bumped it up or down, whether they have read it, the private note on its card preview, and a reply they have held back with Send later. These endpoints read and change that state for the token’s owner — always their own, never anyone else’s, just as in the web app.
All endpoints are POST, take and return JSON, and use the response envelope described in the API overview. None takes an Idempotency-Key.
Endpoints
| Method & path | Ability | Purpose |
|---|---|---|
| POST /api/v1/tickets/user-state | tickets:read | Your bump, read state and note on tickets |
| POST /api/v1/tickets/user-state/update | tickets:write | Bump, mark read or unread, or set the note |
| POST /api/v1/tickets/scheduled | tickets:read | Your replies held with Send later |
| POST /api/v1/tickets/scheduled/cancel | tickets:write | Cancel a held reply |
| POST /api/v1/tickets/scheduled/send-now | tickets:write | Send a held reply now |
| POST /api/v1/tickets/scheduled/reschedule | tickets:write | Move a held reply to another time |
Write implies read. A task is named by its number in the same way as a ticket. Every ticket named must be one the token’s owner can see — as its assignee (in person or through a team), a participant, or with access to its queue. For bump, read and note, a selection that names any other ticket, or a number that is no ticket, is refused whole with 404 (No such ticket, or not one the token owner can see), listing those numbers without saying which is which. For the Send later endpoints, an unknown ticket number gives 404 and a ticket the owner cannot see 403.
Bump, read and note
Reading. tickets/user-state takes ticket_numbers (up to 500) and returns, for each ticket:
bumped_upandbumped_down;read— whether the owner has opened the ticket since its latest customer or staff message, as the ticket list’s unread count has it — withopened_response_idandopened_at, the message or note they had read up to and when;note— their private note on the card preview, as{ text, at }, ornull.
Changing. tickets/user-state/update takes ticket_numbers and any of:
bump—upordown(each clears the other), ornoneto clear both. Bumped tickets move to the top or bottom of the owner’s ticket lists at once.read—truemarks every message or note read;falsemakes the ticket unread again.note— the private note, up to 2,000 characters;nullor an empty string removes it.
curl -X POST https://support.sole-provider.example/api/v1/tickets/user-state/update \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "ticket_numbers": ["528641"], "bump": "up", "note": "Waiting on the courier" }' The reply has the same shape as tickets/user-state:
{
"ok": true,
"data": {
"tickets": [
{ "ticket_number": "528641", "bumped_up": true, "bumped_down": false,
"read": true, "opened_response_id": 90412, "opened_at": "2026-11-13T08:52:10+00:00",
"note": { "text": "Waiting on the courier", "at": "2026-11-13T09:05:44+00:00" } }
],
"count": 1
}
} Send later
A reply held with Send later waits until its time and is then posted as if sent at that moment. Each member of staff has at most one held reply per ticket. These endpoints work with the token owner’s own held replies; the reply’s content and attachments stay in their draft on the ticket page.
Listing. tickets/scheduled takes an optional ticket_number or ticket_id; without one it lists all of the owner’s held replies. Each has its ticket_number, subject, send_at, status — pending; editing, while it is open in the owner’s editor, which holds it; or failed, with the error — and reply: the content, subject, and the status, priority, assignee, queue, message type and dates it will set.
Cancelling. scheduled/cancel takes ticket_number or ticket_id and stops the owner’s held reply on that ticket. The draft stays, as it does on the ticket page.
Sending now. scheduled/send-now posts the held reply at once, through the same path as Send. It is refused (422 refused) while the reply is open in the owner’s editor, while it is already being sent at its scheduled time, or when the ticket would refuse it — for example, while someone else has it locked. Called from an Axial agent task, it sends nothing: the reply waits for a person’s approval as a card on the task’s ticket (or, for a task that is not on a ticket, on the ticket named), and the call returns 202 with status: "awaiting_approval" and the card’s approval_id. From a reply task, which only reads, the call is refused with 403 and nothing is sent.
Rescheduling. scheduled/reschedule takes send_at, an ISO 8601 date and time more than 30 seconds ahead, and moves the held reply there, keeping its content. A failed reply is tried again at the new time.
A ticket where the owner has no held reply gives 404, whether or not someone else has one there.