Workflow 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 Workflow API exposes the Workflow admin screens — queues, resolution categories, interventions, escalations and business hours. Every endpoint runs as the token’s owner and is gated by the workflow ability plus the owner’s admin role, and (for some features) the same plan entitlement the UI requires. (FAQs are managed through the Templates API; the intervention runtime contract is the Interventions technical reference.)

Abilities and conventions

workflow:read — read endpoints.
workflow:write — create / update / delete. Write implies read.

All endpoints are POST and JSON. Resolution categories require the resolution tracking plan feature, interventions the interventions feature, and escalations/business hours the escalations feature — a call without the entitlement is rejected, just as the screen is hidden in the UI.

Endpoints

Method & path	Ability	Purpose
POST /api/v1/workflow/queues	workflow:read	List queues (with ticket counts)
POST /api/v1/workflow/queues/create	workflow:write	Create a queue (`name`, `outgoing_mailbox_id`)
POST /api/v1/workflow/queues/update	workflow:write	Update a queue by `queue_id`; only the fields sent change
POST /api/v1/workflow/queues/delete	workflow:write	Delete a queue by `queue_id` (blocked if built-in / in use)
POST /api/v1/workflow/queues/move	workflow:write	Move every ticket from one queue to another (`from_queue_id`, `to_queue_id`)
POST /api/v1/workflow/resolution-categories	workflow:read	List resolution categories
POST /api/v1/workflow/resolution-categories/create	workflow:write	Create a category
POST /api/v1/workflow/resolution-categories/update	workflow:write	Update a category by `id`
POST /api/v1/workflow/resolution-categories/delete	workflow:write	Delete a category by `id` (blocked if in use)
POST /api/v1/workflow/resolution-categories/reorder	workflow:write	Reorder categories (`ids`)
POST /api/v1/workflow/interventions	workflow:read	List interventions (never returns remote tokens)
POST /api/v1/workflow/interventions/create	workflow:write	Create an intervention (+ fields)
POST /api/v1/workflow/interventions/update	workflow:write	Update an intervention by `intervention_id`
POST /api/v1/workflow/interventions/delete	workflow:write	Delete an intervention by `intervention_id`
POST /api/v1/workflow/interventions/generate-token	workflow:write	Mint a remote bearer token (`intervention_id`, `remote_name`; returned once)
POST /api/v1/workflow/escalations	workflow:read	List escalations + business hours
POST /api/v1/workflow/escalations/create	workflow:write	Create an escalation
POST /api/v1/workflow/escalations/update	workflow:write	Update an escalation by `id`
POST /api/v1/workflow/escalations/delete	workflow:write	Delete an escalation by `id`
POST /api/v1/workflow/business-hours/update	workflow:write	Update business hours

Queues

Listing. queues returns every queue with its ticket counts (total, closed and unclosed), the mailbox it is the inbox for, whether perspectives refer to it and its release queue’s name, together with the mailboxes a queue can send from.

Creating. queues/create takes name (unique) and outgoing_mailbox_id, both required, plus optional track_resolutions, content_type (ticket, the default, or task), is_parked and release_queue_id. The plan’s custom-queue limit applies, and track_resolutions needs the resolution tracking plan feature. The reply carries the new queue_id.

Updating. queues/update takes queue_id and changes only the fields sent: name, outgoing_mailbox_id, track_resolutions, content_type, is_parked and release_queue_id each keep their value when left out. A parked queue stays parked, with its release queue, until a call sends is_parked: false. For example, to rename a queue:

{
  "queue_id": 7,
  "name": "Sales enquiries"
}

Parked queues. A parked queue must name a release queue, and that release queue must exist, must be a different queue, must not itself be parked and cannot be Drafts. A create or update that breaks one of these rules is refused with 422 and a my_error message; un-parking a queue clears its release queue.

Deleting and moving. queues/delete refuses a built-in queue, a queue that still holds tickets and a queue a perspective refers to. To empty a queue first, queues/move moves all of its tickets to another queue and returns the moved_count.

Other updates

The resolution-category, intervention and escalation update endpoints take the complete record each time, as the editor does: send every field, including those that are not changing. Business hours are likewise updated as a whole — mode (always_on, simple or per_day), each day’s enabled flag and the times. For an intervention that includes its fields list. An intervention’s name is fixed once it is created, and its remote bearer token is replaced only when a new one is sent.