Create a workflow status

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

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

Adds a status to a workflow and returns it with a Location header, mirroring the status list in plnnrly's workflow form.

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: A resolved column

curl -X POST \
  'https://<your-url>/api/v2/workflow-statuses' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <key>' \
  -d '{
    "workflow_id": 4,
    "name": "Done",
    "color": "#22c55e",
    "is_resolution": true
  }'

const response = await fetch('https://<your-url>/api/v2/workflow-statuses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': '<key>',
  },
  body: JSON.stringify({
    "workflow_id": 4,
    "name": "Done",
    "color": "#22c55e",
    "is_resolution": true
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('Idempotency-Key', '<key>')
    ->post('https://<your-url>/api/v2/workflow-statuses', [
        'workflow_id' => 4,
        'name' => 'Done',
        'color' => '#22c55e',
        'is_resolution' => true,
    ]);

import requests
response = requests.request(
    'POST',
    'https://<your-url>/api/v2/workflow-statuses',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'Idempotency-Key': '<key>'},
    json={'workflow_id': 4, 'name': 'Done', 'color': '#22c55e', 'is_resolution': True},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "workflow_id": 4,
    "name": "Done",
    "color": "#22c55e",
    "is_resolution": true,
    "order": 1,
    "created_at": "2026-03-04T09:15:00Z",
    "updated_at": "2026-03-04T09:15:00Z",
    "workflow": {
      "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."
    }
  ]
}

order is not accepted: the new status is created at position 0 and is reordered only by dragging it in plnnrly. color must be six-digit hex, because it is re-validated on every read. A new status is unreachable until you also create the transitions leading into it: a work item can only be moved along an edge the workflow publishes.

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 status belongs to. A status cannot be moved to another workflow: its transitions and the work items sitting in it belong to this one.

namestring≤ 255Required

Status name as shown on the board column and the status badge, e.g. To do.

colorstring≤ 255Required

Six-digit hex colour, e.g. #6b7280. A stored value that is not six-digit hex reads back as #6b7280, so writing this field back unchanged replaces the malformed original.

hex colour, e.g. #7c31e8

is_resolutionboolean

Whether a work item reaching this status counts as resolved. Drives the backlog's done state and what a completed sprint carries over.

Response 201

Returns a WorkflowStatus 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