Create a workflow transition

POSThttps://<your-url>/api/v2/workflow-transitions

MCP id workflow-transitions.storeAlso on this path: GET List workflow transitions

Adds a legal status move to a workflow and returns it with a Location header, mirroring the "add transition" action in plnnrly.

Token scope: api:write:workflows
Without it: 403 insufficient-token-scope.
Permission: workflows::create
Without it: 403 insufficient-permission.
Feature: Needs the sprints feature on your organisation.
Without it: 404 endpoint-not-found.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: Accepts Idempotency-Key. 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: Allow moving from To do to In progress

curl -X POST \
  'https://<your-url>/api/v2/workflow-transitions' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "workflow_id": 4,
    "from_status_id": 11,
    "to_status_id": 12,
    "name": "Start progress"
  }'

const response = await fetch('https://<your-url>/api/v2/workflow-transitions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "workflow_id": 4,
    "from_status_id": 11,
    "to_status_id": 12,
    "name": "Start progress"
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/workflow-transitions', [
        'workflow_id' => 4,
        'from_status_id' => 11,
        'to_status_id' => 12,
        'name' => 'Start progress',
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/workflow-transitions',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'workflow_id': 4, 'from_status_id': 11, 'to_status_id': 12, 'name': 'Start progress'},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "workflow_id": 4,
    "from_status_id": 11,
    "to_status_id": 12,
    "name": "Start progress",
    "created_at": "2026-03-04T09:15:00Z",
    "updated_at": "2026-03-04T09:15:00Z",
    "workflow": {
      "id": 1
    },
    "from_status": {
      "id": 1
    },
    "to_status": {
      "id": 1
    },
    "links": {
      "self": "https://<your-url>/api/v2/work-items/1"
    }
  }
}

{
  "type": "https://developers.plnnrly.com/api/v2/problems/idempotency-key-in-flight",
  "title": "Idempotency key in flight",
  "status": 409,
  "detail": "The original request for this Idempotency-Key is still being processed. Retry shortly.",
  "instance": "/api/v2/worklogs",
  "request_id": "01K4B7Q9YV3PZ2N8T1E6M0XR4S"
}

{
  "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."
    }
  ]
}

Both statuses must belong to the workflow named in workflow_id, and they must differ; a status from another workflow is refused as if it did not exist. The three ids are validated together, so an unusable workflow_id also fails both status fields. Duplicate edges are legal, exactly as they are in plnnrly. The work-item transition endpoint accepts the new move as soon as this call returns.

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.

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_idinteger → Workflow.idRequired

Workflow this edge belongs to. Both statuses belong to the same workflow, and the edge cannot be moved to another one.

from_status_idinteger → WorkflowStatus.idRequired

Status a work item must currently be in for this edge to apply.

to_status_idinteger → WorkflowStatus.idRequired

Status the work item moves to. Always different from from_status_id.

Must differ from from_status_id.

namestring≤ 255Required

Transition label as shown on the status button, e.g. Start progress.

Response 201

Returns a WorkflowTransition 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.
Location: The absolute URL of the created or queued resource.
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