Adding and Reordering Tickets in a Workspace Group
This article covers the payloads used to add a ticket to a workspace and to reorder tickets within a group. For an explanation of the anchor-based positioning model, see How Workspace Ordering Works.
Two ways to move a ticket
Ticket placement can be controlled at two levels, depending on which endpoint you call:
Endpoint | Use case |
| Move or add a ticket at the workspace level — you specify which group the ticket should belong to (or leave it unspecified to use the default group). |
| Move or add a ticket within a specific group — the group is already identified by the route, so it isn't repeated in the payload. |
In both cases, {entityId} in the route refers to the workspace's entity ID.
Workspace-level move: WorkspaceTicketAction
export interface WorkspaceGroupTicketAction {
readonly entityIds: ReadonlyArray<number>;
readonly operator: WorkspaceMovement;
readonly anchorBeforeEntityId?: number;
readonly anchorAfterEntityId?: number;
}
export interface WorkspaceTicketAction extends WorkspaceGroupTicketAction {
readonly groupEntityId?: string;
}Field | Description |
| The ticket ID(s) to add or move. Multiple tickets can be moved in a single call. |
| One of the |
| Optional. The ticket ID you want to end up before. |
| Optional. The ticket ID you want to end up after. |
| Optional. The group the ticket(s) should belong to. If omitted, the workspace's default group is used. |
Because this endpoint doesn't require a group to be identified in the route, groupEntityId needs to be included in the payload instead, so the server knows which group's ordering to place the ticket into.
Note: if you omit groupEntityId (i.e. you're relying on the default group), use move-top or move-bottom rather than move-between. Without an explicit group, there isn't a reliable, well-defined position to anchor "between" against, so move-top/move-bottom are the appropriate operators in this case.
Group-level move: WorkspaceGroupTicketAction
export interface WorkspaceGroupTicketAction {
readonly entityIds: ReadonlyArray<number>;
readonly operator: WorkspaceMovement;
readonly anchorBeforeEntityId?: number;
readonly anchorAfterEntityId?: number;
}This is the same shape as above, minus groupEntityId — since the group is already identified by {groupEntityId} in the route, it doesn't need to be repeated in the payload. All three WorkspaceMovement operators (move-between, move-top, move-bottom) are fully supported here, since the group context is always known.
Failure behavior
- If a specified
groupEntityId(workspace-level endpoint) does not exist, the request fails. Groups are treated as a relatively stable, low-churn entity, so referencing a non-existent group is treated as a genuine error rather than something to silently fall back from. - If anchors can't be resolved (e.g. an anchor ticket no longer exists), the operation falls back to the bottom of the target group rather than failing — see How Workspace Ordering Works for the full reasoning and concurrency guarantees.
- The move otherwise always succeeds, unless the ticket doesn't exist, the workspace doesn't exist, or the caller lacks permission to modify the workspace.
Sample usages
Adding a ticket to a workspace when it's created and matches certain criteria
If you don't know (or don't need to specify) a particular group, you can omit groupEntityId entirely and just set operator to move-top or move-bottom. The system will place the ticket into the workspace's default group automatically — you don't need to look up or track a group ID for this case.
Moving a ticket between groups when its status changes
This is where knowing the target groupEntityId matters — for example, moving a ticket into a "Done" group when it's marked resolved. For automations like this, you'll almost always use move-top or move-bottom rather than move-between. Anchoring a move relative to another specific ticket (move-between) is really a UI-driven concept — useful when a person is manually dragging a ticket to a precise spot — but isn't typically something an automation rule needs to reason about.
A note on repeated automation runs
Currently, a move operation is always applied, even if the ticket is already in the target group. This means that if an automation repeatedly moves a ticket to, say, move-top of the same group every time its status is re-evaluated, the ticket will keep jumping to the top each time — even if it hasn't actually changed groups.
We're considering adding a flag in the future to make this behavior optional (e.g., skip the move if the ticket is already in the target group and not necessarily at the very top/bottom). This isn't implemented yet, and we're waiting to see how automation usage develops before committing to a specific approach — so for now, keep in mind that repeated automation triggers will re-apply the move each time, regardless of the ticket's current position.
If you need to check a ticket's current position before deciding whether to move it, avoid repeatedly calling the Workspace API with workspace.tickets-include: include just to check where a ticket currently sits. While the API is built to handle this reliably, calling it at a high frequency purely to poll for a ticket's location adds unnecessary load and isn't a good pattern to rely on — even if performance holds up under it. If your automation needs this kind of check, consider tracking the ticket's last known group on your own side (e.g., from the status change event that triggered the move) rather than re-querying the workspace repeatedly.
