Watchlists 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.
A watchlist is a hand-picked list of tickets: a private one a member of staff keeps for themselves, or a shared one the whole team sees. These endpoints, in the Settings family, find watchlists, create and change them, and put tickets on and off them in the order you choose.
All endpoints are POST, take and return JSON, and use the response envelope described in the API overview. None takes an Idempotency-Key. A change to which tickets are on a watchlist refreshes the perspectives and open ticket lists that show it.
Endpoints
| Method & path | Ability | Purpose |
|---|---|---|
| POST /api/v1/settings/watchlists | settings:read | List watchlists, filtered, optionally with their tickets |
| POST /api/v1/settings/watchlists/create | settings:write | Create a watchlist |
| POST /api/v1/settings/watchlists/update | settings:write | Rename or restyle a watchlist |
| POST /api/v1/settings/watchlists/delete | settings:write | Delete a watchlist |
| POST /api/v1/settings/watchlists/add-tickets | settings:write | Put tickets on a watchlist |
| POST /api/v1/settings/watchlists/remove-tickets | settings:write | Take tickets off a watchlist |
| POST /api/v1/settings/watchlists/reorder | settings:write | Put a watchlist’s tickets in a new order |
Write implies read. The token’s owner must be a member of staff.
Who may do what
- Everyone sees the shared watchlists and their own private ones; an admin also sees that other people’s private watchlists exist, but not which tickets are on them.
- A shared watchlist is created, renamed and deleted by an admin. Any member of staff can put tickets on it and take them off, as on the ticket page; its tickets are reordered by an admin.
- A private watchlist is changed by its owner; an admin may also rename or delete it. Which tickets are on it, and their order, are changed by its owner alone.
- Tickets are added and reordered only when the token’s owner can see every one of them: as assignee (in person or through a team), participant, or with access to its queue. A ticket can be taken off a watchlist the owner may change even when they can no longer see it, or it has been deleted.
- The built-in Axial notes watchlist is kept by Tickiti itself: a ticket is on it while a shared note on it waits for a manager. Its tickets cannot be changed through the API.
List watchlists
POST /api/v1/settings/watchlists With no body, returns every watchlist the owner can see, each with its ticket count and whether it is in their perspectives, with the colours still free for new watchlists and, for an admin, the list of users. Every filter is optional:
id— one watchlist.name— part of the name, in any case.owner—me, a user id or an email address.shared—truefor shared watchlists only,falsefor private ones.with_tickets— adds each watchlist’sticketsin their order (number, subject, status; up to 500, and only tickets the owner can see). On someone else’s private watchlistticketsisnull.include_users—falseleaves out the user list, which keeps an admin’s reply short.
{ "name": "returns", "with_tickets": true, "include_users": false } Create, update and delete
Creating. watchlists/create takes name, icon and shared, with optional description, display_mode (card or list), show_in_my_perspectives and ticket_ids to start it with. A watchlist created by someone who is not an admin is private whatever shared says. The plan’s watchlist limits apply.
Updating. watchlists/update takes watchlist_id with name and icon on every call, and optional description, display_mode and show_in_my_perspectives. A watchlist’s owner and whether it is shared stay fixed while it holds tickets.
Deleting. watchlists/delete takes watchlist_id. A watchlist that still holds tickets is left in place, with a my_error giving its ticket_count; send force: true to delete it anyway. The tickets themselves are untouched.
Tickets on a watchlist
watchlists/add-tickets, watchlists/remove-tickets and watchlists/reorder each take watchlist_id and the tickets as ticket_numbers, ticket_ids or both (up to 500 of each). A ticket number that does not exist is refused (422 validation_failed, naming it), and so is a call that names no tickets. When removing, a deleted ticket still counts as existing, so it can be taken off.
- Adding puts new tickets at the end of the watchlist; tickets already on it keep their place.
show_in_my_perspectives: truealso adds the watchlist to the owner’s perspectives. - Removing takes the tickets off and returns
detached_count. - Reordering gives the watchlist’s tickets in their new order; a watchlist’s own perspective is sorted by it.
curl -X POST https://support.sole-provider.example/api/v1/settings/watchlists/add-tickets \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "watchlist_id": 12, "ticket_numbers": ["528641", "871546"] }' Someone else’s private watchlist, the Axial notes watchlist, or, when adding or reordering, a ticket the owner cannot see, is refused with 403 and nothing changes. So is a shared watchlist reordered by someone who is not an admin.
To find the tickets on a watchlist from a ticket search, use the watchlist search mode of tickets/query; see List tickets API. The other Settings endpoints are described in the Settings API.