Read a task

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

MCP id tasks.showAlso on this path: PATCH Update a task, DELETE Delete a task

Returns one kanban task with its budget and the employee it belongs to.

Token scope: api:read:kanban
Without it: 403 insufficient-token-scope.
Permission: kanban::manage_self
Without it: 403 insufficient-permission.
Rate cost: 1 unit, read bucket.
Also: If-None-Match answers 304 when nothing changed. Never cached: private, no-store. Unknown query parameters are refused, never ignored.

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

Request

Example: One task

curl -X GET \
  'https://<your-url>/api/v2/tasks/1' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

const response = await fetch('https://<your-url>/api/v2/tasks/1', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
  },
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->get('https://<your-url>/api/v2/tasks/1');

import requests
response = requests.request(
    'GET',
    'https://<your-url>/api/v2/tasks/1',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json'},
)

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": "on-hold",
    "order_column": 1
  }
}

5 more fields, listed under Response

Tasks are per-user: a caller sees only their own unless they hold kanban::manage_for_others, and an id outside that scope is 404 rather than 403, so the endpoint cannot be walked to discover a colleague's cards. Tasks are hard-deleted, so a deleted one is simply 404 and trashed is not an accepted parameter. The task's project is not in the payload (a task has no project_id of its own, and the budget object carries only id and description), so a client that needs the project follows GET /api/v2/budgets/{budget}. The summary and detail views are identical on this resource.

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-None-Matchstring

The ETag a read is conditional on. A match is answered 304 with no body.

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

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.

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.