List work items

GEThttps://<your-url>/api/v2/work-items

MCP id work-items.indexAlso on this path: POST Create a work item

Returns the work items the caller may read, in each sprint's display order with the id as the tiebreaker.

Token scope: api:read:project_management
Without it: 403 insufficient-token-scope.
Permission: project_management::view_backlog
Without it: 403 insufficient-permission.
Rate cost: 1 unit, read bucket. view=detail makes it 3. Adds: with_total=1 +2, each include +1 (to-many +3), q +2.
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 project's open backlog, highest priority first

curl -G \
  'https://<your-url>/api/v2/work-items' \
  --data-urlencode 'filter[project_id]=1' \
  --data-urlencode 'filter[sprint_id][null]=true' \
  --data-urlencode 'filter[resolved]=false' \
  --data-urlencode 'sort=order' \
  --data-urlencode 'with_total=1' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

const response = await fetch('https://<your-url>/api/v2/work-items?filter[project_id]=1&filter[sprint_id][null]=true&filter[resolved]=false&sort=order&with_total=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/work-items?filter[project_id]=1&filter[sprint_id][null]=true&filter[resolved]=false&sort=order&with_total=1');

import requests
response = requests.request(
    'GET',
    'https://<your-url>/api/v2/work-items?filter[project_id]=1&filter[sprint_id][null]=true&filter[resolved]=false&sort=order&with_total=1',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json'},
)

Response

The shape of the response, with sample values.

{
  "data": [
    {
      "id": 1,
      "issue_key": "ACM-123",
      "title": "Portal login rejects SSO users",
      "priority": "high",
      "due_date": "2026-03-04",
      "estimation": 240,
      "remaining_estimate": 1,
      "order": 1,
      "column_order": 1,
      "version": 1,
      "created_at": "2026-03-04T09:15:00Z",
      "updated_at": "2026-03-04T09:15:00Z"
    }
  ],
  "meta": {
    "page": {
      "per_page": 1,
      "next_cursor": "…",
      "prev_cursor": "…",
      "total": 1
    },
    "warnings": [
      {
        "…": "6 fields of warnings"
      }
    ]
  },
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1",
    "next": "https://<your-url>/api/v2/work-items/1",
    "prev": "https://<your-url>/api/v2/work-items/1"
  }
}

23 more fields, listed under Response

The list covers the whole organisation and interleaves projects, because order is unique within a sprint only; narrow it with filter[project_id], and add filter[sprint_id][null]=true for a project's backlog or filter[resolved]=false for its open work. Pagination is cursor-only: a backlog drag rewrites order on the rows behind you, so an offset page would skip and repeat items. meta.page.total is null unless you pass with_total=1, which costs two rate units. Listing additionally requires project_management::manage_work_items. Defaults to the summary view, which omits description; pass view=detail for the full payload.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

43 parameters in 6 groups

Views

viewstring

Which field set to render.

summarydefaultdetail

Pagination

Cursor pagination only. Follow links.next.

per_pageinteger1 to 100

Rows per page. At most 25 when include names a to-many relation; a larger value is 400 invalid-query-parameter.

Default: 25

cursorstring

Opaque keyset cursor from a previous page's links.next. Never construct one by hand.

with_totalboolean

Whether meta.page.total is counted for this request.

Default: false

Filters

=: equals
[in]: any of a comma-separated list
[null]: true or false: whether it is empty
[gte][lte][lt]: at least, at most, less than
[ne]: not equal

filter[assignee_id]integer=[in][null]

User the work is assigned to. Accepts me. Pass [null] for unassigned items.

A comma-separated list of at most 100 values.

filter[created_at]timestamp (YYYY-MM-DDThh:mm:ssZ)=[gte][lt]

Creation timestamp. Pair with sort=id for a stable full export.

filter[drive_items.id]integer

Work items linked to a given drive document. The document must be one the caller may open; a document they cannot open matches nothing.

Also needs project_drive::access and a token with api:read:project_drive.

filter[due_date]date (YYYY-MM-DD)=[gte][lte][null]

Due date, a zone-free calendar date. Combine [gte] and [lte] for a period; pass [null] for items with no due date.

Whether the field is null.

filter[labels.id]integer

Work items carrying a given label.

filter[parent_id]integer=[in][null]

Parent work item. Pass a key for one item's children (sub-issues), or [null] for top-level items only.

A comma-separated list of at most 100 values.

filter[priority]string=[ne][in]

Relative priority. One of highest, high, normal, low, lowest; there is no medium.

A comma-separated list of at most 100 values.

highesthighnormallowlowest

New values may be added.

filter[project_id]integer=[in]

Project the work item belongs to. This is how a client reproduces one project's backlog; combine it with the other filters to hit idx_work_items_project_sprint_order and its siblings.

A comma-separated list of at most 100 values.

filter[reporter_id]integer=[in]

User who filed the work item. Accepts me.

A comma-separated list of at most 100 values.

filter[resolved]boolean

Whether the item sits in a workflow status marked as a resolution. Pass false for open work.

Also needs workflows::read and a token with api:read:workflows.

Search

qstring

Free-text search over title, issue_key, in that order of relevance. At most one substring match per request: q together with a contains filter is 400 invalid-query-parameter.

Sorting

sortstring

Up to three keys, comma-separated, each optionally prefixed with - for descending.

Default: order

Key	Sorts by
`order`	Position within the sprint or backlog, as ordered in plnnrly. The default sort, ascending.
`column_order`	Position within the board column.
`title`	Work item title, A→Z.
`due_date`	Due date, earliest first.
`priority`	Priority, ordered by its stored value rather than by severity: high, highest, low, lowest, normal.
`id`	Id, ascending. An id never changes, so use this for a stable full export.
`updated_at`	Last-write timestamp; pair with the id tiebreaker for sync.

Prefix a key with - for descending.

Includes

includestring

Comma-separated names to inline, at most five.

Path	Adds	Cost
`assignee`	The user the work is assigned to. Requires the users prefix's read grant and a token scope covering it.	+1
`comments`	Comments on this work item, capped at 25 rows. Truncation emits an `include_truncated` warning; `links.comments` is the paginated continuation.	to-many · +3
`drive_items`	Drive documents linked to this work item, capped at 25 rows and narrowed to the ones you may open. `links.drive_items` is the paginated list of all of them. Requires the `project_drive` prefix's access grant and a token scope covering it.	to-many · +3
`labels`	Labels on this work item in the project's label order, capped at 25 rows. While the Sprints feature is enabled, `links.labels` is the paginated list of all of them.	to-many · +3
`parent`	The parent work item, on a sub-issue.	+1
`reporter`	The user who filed the work item. Requires the users prefix's read grant and a token scope covering it.	+1
`sprint`	The sprint this item sits in, when it is not in the backlog.	+1
`subtasks`	Checklist subtasks on this work item, capped at 25 rows. `links.subtasks` is the paginated continuation.	to-many · +3
`work_type`	The work type of this item. Requires the `work_types` prefix's read grant and a token scope covering it.	+1

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 page of WorkItemList rows.

dataarray of WorkItemList

The rows, each a WorkItemList.

meta.pagePageOptionalTotal

per_page, next_cursor, prev_cursor, total.

meta.warningsarray of object

Non-fatal notes about this request. Switch on code, never on detail.

linksPageLinks

self, next, prev.

Each row is a WorkItemList: 39 fields.

Headers

ETag: A weak validator (W/"…") of the rendered page.
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

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

304 Not modified.

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 GET, POST. Anything else answers 405.

Something wrong or missing on this page? Tell us

Access

Query parameters

Views

Pagination

Filters

Search

Sorting

Includes

Request headers

Response 200

Headers

Errors