Transition a work item

POSThttps://<your-url>/api/v2/work-items/{work_item}/actions/transition

MCP id work-items.actions.transition

Moves a work item to another workflow status.

Token scope: api:write:project_management
Without it: 403 insufficient-token-scope.
Permission: project_management::manage_work_items
Without it: 403 insufficient-permission.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: Accepts Idempotency-Key. Accepts If-Match. Never cached: private, no-store. Unknown body keys are refused, never dropped.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: Move to In review

curl -X POST \
  'https://<your-url>/api/v2/work-items/1/actions/transition' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "workflow_status_id": 1
  }'

const response = await fetch('https://<your-url>/api/v2/work-items/1/actions/transition', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "workflow_status_id": 1
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/work-items/1/actions/transition', [
        'workflow_status_id' => 1,
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/work-items/1/actions/transition',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'workflow_status_id': 1},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "issue_key": "ACM-123",
    "title": "…",
    "description": "<p>…</p>",
    "priority": "highest",
    "due_date": "2026-03-04",
    "estimation": 1,
    "remaining_estimate": 1,
    "location_name": "…",
    "location_address": "…",
    "location_latitude": "45.00",
    "location_longitude": "90.00"
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/state-conflict",
  "title": "State conflict",
  "status": 409,
  "detail": "The target status is not reachable from this work item's current status.",
  "instance": "/api/v2/work-items/812/actions/transition",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "conflict": {
    "reason": "illegal_transition",
    "from_workflow_status_id": 3,
    "to_workflow_status_id": 9
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/precondition-failed",
  "title": "Precondition failed",
  "status": 412,
  "detail": "The record changed since the version named in If-Match. Re-read it and retry.",
  "instance": "/api/v2/work-items/812",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "current_version": 12
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "3 fields failed validation.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S",
  "errors": [
    {
      "pointer": "/date",
      "code": "date_format",
      "detail": "The date does not match the format Y-m-d."
    },
    {
      "pointer": "/minutes",
      "code": "min",
      "detail": "The minutes must be at least 1."
    },
    {
      "pointer": "/description",
      "code": "required",
      "detail": "The description field is required."
    }
  ]
}

28 more fields, listed under Response

The move is validated against the project workflow: statuses not reachable from the current one are rejected with 409 state-conflict and conflict.reason illegal_transition, naming both ends of the attempted move. For the reachable statuses, send GET /api/v2/workflow-transitions?filter[from_status_id]={id} with the item's current workflow_status_id as the id; each to_status_id is a legal target. Transitioning to the status the item already sits in succeeds and is a no-op, so a retry is safe. Returns the mutated work item in the detail view with a fresh ETag, and bumps version once.

Path parameters

work_iteminteger or stringRequired

The WorkItem's numeric id. Or its issue_key, matching [A-Z][A-Z0-9]*-[0-9]+.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

viewstring

Which field set to render.

summarydetaildefault

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

If-Matchstring

The ETag a write is conditional on. A stale validator is 412 precondition-failed.

Idempotency-Keystring≤ 255

A caller-chosen key that makes this POST safe to retry. Replaying it returns the original response with Idempotency-Replayed: true.

Request body

Unknown keys are refused with 422, naming the key.

workflow_status_idinteger → WorkflowStatus.idRequired

Status to move the work item to. It must be reachable from the current status in the project workflow.

Response 200

Returns a WorkItem in the detail view.

Headers

ETag: A strong validator of exactly this representation.
Idempotency-Replayed: true when this response was replayed from a stored Idempotency-Key rather than produced by a new write.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning

idinteger

Unique identifier.

issue_keystring or null≤ 255Server-assigned

Human-readable key, e.g. ACM-123, allocated by the server from the project's customer code and a per-customer sequence. It also works in the path: GET work-items/ACM-123 works. This is one of the two fields ?q= searches.

titlestring≤ 255

Work item title. The other field ?q= searches.

descriptionhtml or nullDetail only

Work item description. HTML from the rich editor, sanitised on read and on write. Mention spans are preserved verbatim, so pass them back unchanged. Detail view only.

prioritystring or null

Relative priority. Defaults to normal on create; null only on a legacy item that was never prioritised.

highesthighnormallowlowest

New values may be added.

due_datedate (YYYY-MM-DD) or null

Due date, a zone-free calendar date. Null when no date was set.

estimationinteger or null

Original estimate, in minutes.

remaining_estimateinteger or null

Remaining estimate, in minutes. Null where none was entered, in which case plnnrly derives one from the estimate and the logged time.

location_namestring or null≤ 255Detail only

Name of the place the work happens, as picked from the address search in plnnrly. Null when no location was set. Send it together with location_latitude and location_longitude; null all three to clear the location. Detail view only.

location_addressstring or null≤ 255Detail only

Formatted address of the location, when the place has one. Detail view only.

location_latitudedecimal (2 dp) or null-90 to 90patternDetail only

Latitude of the location in decimal degrees, -90 to 90. Detail view only.

location_longitudedecimal (2 dp) or null-180 to 180patternDetail only

Longitude of the location in decimal degrees, -180 to 180. Detail view only.

orderintegerServer-assigned

Position within the sprint or backlog, and the default sort. Not writable through PATCH: move an item with POST work-items/{work_item}/actions/move and list: backlog.

column_orderinteger or nullServer-assigned

Position within the board column. Not writable through PATCH: move a card with POST work-items/{work_item}/actions/move and list: board.

versioninteger

Revision counter, bumped once per write. It is the ETag's revision: send it back as If-Match to detect a concurrent edit, which answers 412.

created_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Creation timestamp.

updated_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Last-write timestamp; use for incremental sync.

project_idinteger

Project this work item belongs to. It cannot change: the issue key was allocated from the project's customer code.

task_idinteger or null

Kanban task this work item is booked against, when it is booked against one. It must belong to the item's project. A sprint project books the running sprint's hours through it, so an item in that project's running sprint needs one; a simple-mode project does not. Setting it also makes the task's owner the assignee. Follow it to /api/v2/tasks/{task}.

workflow_status_idinteger

Current workflow status. Not writable through PATCH: moving between statuses is POST work-items/{work_item}/actions/transition, because the move is validated against the project workflow.

work_type_idinteger

Work type of this item.

sprint_idinteger or null

Sprint the item sits in. Null means it is in the backlog.

parent_idinteger or null

Parent work item, for a sub-issue. Null on a top-level item.

assignee_idinteger or null

User the work is assigned to. Null on an unassigned item. On a sprint project, setting it also moves the item to that user's only open task in the same budget, or in the project when the item has no task yet; with several or no candidates the task is left as it is.

reporter_idintegerServer-assigned

User who filed the work item. Always the authenticated user at create time; there is no way to file on somebody else's behalf.

web_urlstring

Absolute URL that opens this work item in plnnrly, on the organisation's own hostname. It is a stable link, safe to store: it redirects to the first of the project's backlog, all-work list or board the signed-in user may open, and opens the item there; it lands on the project page when none of them applies. Read-only.

workflow_statusRef or WorkflowStatusSummary

The workflow status this item currently sits in. Always present.

parentRef or WorkItemSummary or null

The parent work item, on a sub-issue.

assigneeRef or UserSummary or null

The user the work is assigned to. Expanding it additionally requires the users prefix's read grant and a token scope covering it.

reporterRef or UserSummary

The user who filed the work item. Expanding it additionally requires the users prefix's read grant and a token scope covering it.

work_typeRef or WorkTypeSummary

The work type of this item. Expanding it additionally requires the work_types prefix's read grant and a token scope covering it.

sprintRef or SprintSummary or null

The sprint this item sits in, when it is not in the backlog.

comments_countinteger≥ 0

Number of comments on this work item.

subtasks_countinteger≥ 0

Number of checklist subtasks on this work item.

attachments_countinteger≥ 0

Number of files attached to this work item.

child_work_items_countinteger≥ 0

Number of child work items (sub-issues).

labels_countinteger≥ 0

Number of labels on this work item.

drive_items_countinteger≥ 0

Number of linked drive documents the caller may open. Archived documents are not counted.

links_countinteger

Number of work items linked to this one, in either direction.

linksWorkItemLinks

Show 8 child fields

links.selfurl

The canonical URI of this record.

links.commentsurl

Comments on this work item.

links.subtasksurl

Checklist subtasks on this work item.

links.linksurl

Links between this work item and others, in either direction.

links.attachmentsurl

Files attached to this work item.

links.child_work_itemsurl

Child work items (sub-issues) of this work item.

links.labelsurl

Every label on this work item, paginated. Present only while the Sprints feature is enabled, as GET /labels is.

links.drive_itemsurl

Every drive document linked to this work item that you may open, paginated.

labelsarray of LabelSummary≤ 25Only with include

Labels on this work item. label_ids takes at most 50 ids and replaces the whole set: a label you leave out is removed. Build it from links.labels, which lists every label while the Sprints feature is enabled, not from include=labels, which stops at 25.

Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.

Show 3 child fields

labels.idinteger

Unique identifier.

labels.namestring≤ 255

Label name as shown on the chip.

labels.colorstring≤ 255

Six-digit hex colour, e.g. #ef4444.

drive_itemsarray of DriveItemSummary≤ 25Only with include

Drive documents linked to this work item that you may open. drive_item_ids takes at most 25 ids and replaces the whole set: a document you leave out is unlinked, and so is every linked document you cannot open. Build it from links.drive_items, not from include=drive_items, which stops at 25. Expanding it additionally requires the project_drive prefix's access grant and a token scope covering it.

Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.

Show 5 child fields

drive_items.idinteger

Unique identifier.

drive_items.titlestring≤ 255

Item title.

drive_items.owner_typestring

The kind of record owner points at; it says which branch of owner applies.

projectcustomerorganizationuser

New values may be added.

drive_items.owner_idinteger

The id of the record owner points at.

drive_items.ownerRef

The project, customer, organisation or user whose drive this item lives in.

Which form you get depends on owner_type.

project: Ref
customer: Ref
organization: Ref
user: Ref

commentsarray of CommentSummary≤ 25Only with include

Comments on this work item, newest first, capped at 25. Follow links.comments for the rest.

Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.

Show 5 child fields

comments.idinteger

Unique identifier.

comments.author_typestring

The kind of record author points at; it says which branch of author applies.

user

New values may be added.

comments.author_idinteger

The id of the record author points at.

comments.authorRef or UserSummary

Who wrote the comment.

Which form you get depends on author_type.

user: UserSummary

comments.created_attimestamp (YYYY-MM-DDThh:mm:ssZ)

When the comment was posted.

subtasksarray of SubtaskSummary≤ 25Only with include

Checklist subtasks on this work item, capped at 25. Follow links.subtasks for the rest.

Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.

Show 3 child fields

subtasks.idinteger

Unique identifier.

subtasks.titlestring≤ 255

Subtask title.

subtasks.is_resolvedboolean

Whether the subtask is ticked off.

Errors

403 Forbidden.

forbidden-by-policy insufficient-permission insufficient-token-scope

409 Conflict.

idempotency-key-in-flight idempotency-key-reused state-conflict

412 Precondition failed.

precondition-failed

415 Unsupported media type.

unsupported-media-type

422 Unprocessable content.

unprocessable-relationship validation-failed

7 errors every operation can return: 400, 401, 404, 406, 429, 500, 503

400 Bad request.

idempotency-key-required invalid-cursor invalid-query-parameter malformed-request unsupported-parameter

401 Unauthenticated.

token-expired unauthenticated

404 Not found.

endpoint-not-found resource-not-found

406 Not acceptable.

not-acceptable

429 Too many requests.

rate-limit-exceeded

500 Server error.

internal-error

503 Service unavailable.

tenant-unavailable

This path allows POST. Anything else answers 405.

Something wrong or missing on this page? Tell us

Access

Path parameters

Query parameters

Request headers

Request body

Response 200

Headers

Errors