Update a task

PATCHhttps://<your-url>/api/v2/tasks/{task}

MCP id tasks.updateAlso on this path: GET Read a task, DELETE Delete a task

Partially updates a task: absent keys are untouched and an empty body is rejected.

Token scope: api:write:kanban
Without it: 403 insufficient-token-scope.
Permission: kanban::manage_self
Without it: 403 insufficient-permission.
Rate cost: 1 unit, write bucket. A write costs the same whatever view you ask for.
Also: 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 a card to the finished column

curl -X PATCH \
  'https://<your-url>/api/v2/tasks/1' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: *' \
  -d '{
    "status": "finished"
  }'

const response = await fetch('https://<your-url>/api/v2/tasks/1', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'If-Match': '*',
  },
  body: JSON.stringify({
    "status": "finished"
  }),
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->withHeader('If-Match', '*')
    ->patch('https://<your-url>/api/v2/tasks/1', [
        'status' => 'finished',
    ]);

import requests
response = requests.request(
    'PATCH',
    'https://<your-url>/api/v2/tasks/1',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json', 'Content-Type': 'application/json', 'If-Match': '*'},
    json={'status': 'finished'},
)

Response

The shape of the response, with sample values.

{
  "data": {
    "id": 1,
    "budget_id": 1,
    "user_id": 1,
    "team_id": 1,
    "due_date": "2026-03-04",
    "minutes": 1,
    "description": "…",
    "comment": "…",
    "is_finished": false,
    "is_billable": false,
    "status": "finished",
    "order_column": 1
  }
}

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

5 more fields, listed under Response

A status change is a plain PATCH, not an action. Note that the response body can differ from the request body: status and is_finished are cross-synced on every write, so sending is_finished: true answers status: "finished", moving status off finished answers is_finished: false, and re-opening a finished task without naming a status answers status: "active". status wins when both are sent. budget_id is accepted at create time only, so a task cannot be re-budgeted or moved to another project here; user_id, team_id and order_column are not writable at all, which means a task cannot be reassigned to another employee through the API and there is no way to reorder a board. The write also bumps the owning project's updated_at, so the project's ETag changes and it reappears in an incremental filter[updated_at][gte] window, and it lands in that project's activity timeline rather than a timeline of its own. Send If-Match with the ETag from your last read to detect a concurrent edit, which answers 412.

Path parameters

taskintegerRequired

The Task's numeric id.

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.

Request body

Unknown keys are refused with 422, naming the key.

due_datedate (YYYY-MM-DD) or null

Day the task is due. Required when creating a task through the API, and clearable afterwards; tasks created in plnnrly may carry null.

minutesinteger≥ 0

Estimated effort, in minutes.

descriptionstring≤ 255

Short description shown on the kanban card. This is the task's label and the only field ?q= searches.

commentstring or null≤ 255

Optional longer comment on the card, capped at 255 characters.

statusstring

Kanban column the card sits in.

on-hold: Paused, waiting on something off the board.
new: The default for a new card: not picked up yet.
active: Being worked on.
internal-test: Awaiting internal review or testing.
external-test: With the customer for acceptance.
finished: Done. The only status for which is_finished is true.

New values may be added.

is_finishedboolean

Whether the task is done. Cross-synced with status on every write: setting status to finished sets this true and any other status sets it false, while setting this false on a finished task moves status back to active. status wins when both are sent.

is_billableboolean

Whether time logged on this task is billable. Defaults to true when a task is created through the API, regardless of the budget's own setting.

Response 200

Returns a Task in the detail view.

Headers

ETag: A strong validator of exactly this representation.
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.

budget_idinteger

Budget the task is filed under. This is the task's only link to a project (a task has no project_id of its own), and it is settable at create time only; a task cannot be re-budgeted through the API.

user_idinteger or nullServer-assigned

The employee the task belongs to. Always the authenticated user on create; not writable. Null on a task left unassigned in plnnrly.

team_idinteger or nullServer-assigned

Team the task is filed under. Nothing on the API path assigns it, so a task created through the API always carries null; plnnrly itself is the only place a team is set. Not writable, and there is no team object beside it.

due_datedate (YYYY-MM-DD) or null

Day the task is due. Required when creating a task through the API, and clearable afterwards; tasks created in plnnrly may carry null.

minutesinteger

Estimated effort, in minutes.

descriptionstring≤ 255

Short description shown on the kanban card. This is the task's label and the only field ?q= searches.

commentstring or null≤ 255

Optional longer comment on the card, capped at 255 characters.

is_finishedboolean

is_billableboolean

Whether time logged on this task is billable. Defaults to true when a task is created through the API, regardless of the budget's own setting.

statusstring

Kanban column the card sits in.

on-holdnewactiveinternal-testexternal-testfinished

New values may be added.

order_columnintegerServer-assigned

Position on the kanban board, lowest first. Appended to the end of the board on create and changed when someone drags the card in plnnrly. Not writable.

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

Creation timestamp.

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

Last-write timestamp; use for incremental sync.