List projects

GEThttps://<your-url>/api/v2/projects

MCP id projects.indexAlso on this path: POST Create a project

Returns the projects the caller may read, with their customer, sub-customer, project manager and account manager inlined.

Token scope: api:read:projects
Without it: 403 insufficient-token-scope.
Permission: projects::read
Without it: 403 insufficient-permission.
Rate cost: 1 unit, read bucket. view=detail makes it 3. Adds: 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: Active projects for one customer

curl -G \
  'https://<your-url>/api/v2/projects' \
  --data-urlencode 'filter[status]=active' \
  --data-urlencode 'filter[customer_id]=1' \
  --data-urlencode 'sort=-start_date' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

const response = await fetch('https://<your-url>/api/v2/projects?filter[status]=active&filter[customer_id]=1&sort=-start_date', {
  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/projects?filter[status]=active&filter[customer_id]=1&sort=-start_date');

import requests
response = requests.request(
    'GET',
    'https://<your-url>/api/v2/projects?filter[status]=active&filter[customer_id]=1&sort=-start_date',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json'},
)

Response

The shape of the response, with sample values.

{
  "data": [
    {
      "id": 1,
      "title": "Portal rebuild",
      "full_title": "…",
      "status": "active",
      "workflow_mode": "sprints",
      "start_date": "2026-03-04",
      "end_date": "2026-03-04",
      "is_billable": true,
      "is_continuous": false,
      "last_activity": "2026-03-04T09:15:00Z",
      "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,
      "current_page": 1,
      "last_page": 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"
  }
}

17 more fields, listed under Response

The default sort is title A→Z, not recent activity; pass sort=-last_activity for that. Defaults to the summary view; pass view=detail for the full payload at three read units instead of one. Pass include=logged_minutes for the worklog total the caller may see.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

52 parameters in 7 groups

Views

viewstring

Which field set to render.

summarydefaultdetail

Pagination

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.

pageinteger1 to 1000

Opt in to page-number paging: 1-based, at most 1000. Omit it, the default, to page by opaque cursor, which is what links.next hands you. Cannot be combined with cursor. Published only on collections that count their rows on every request.

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[account_manager_id]integer=[in][null]

Responsible account manager. Accepts the literal me.

A comma-separated list of at most 100 values.

filter[application_id]integer=[in][null]

Linked application, managed by platform administrators.

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[customer.code]string

Short code of the owning customer, e.g. ACM.

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

filter[customer_id]integer=[in][null]

Owning customer.

A comma-separated list of at most 100 values.

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

Last day of the project.

Whether the field is null.

filter[is_billable]boolean

Whether time is billable.

filter[is_continuous]boolean

Whether the project is open-ended.

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

Most recent write anywhere in the project.

Whether the field is null.

filter[project_manager_id]integer=[in][null]

Responsible project manager. Accepts the literal me.

A comma-separated list of at most 100 values.

Search

qstring

Free-text search over title. 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: title

Key	Sorts by
`title`	Project title, A→Z.
`status`	Lifecycle status.
`start_date`	First day of the project.
`end_date`	Last day of the project.
`last_activity`	Most recent write anywhere in the project.
`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
`logged_minutes`	Sum of the worklog minutes on this project that the caller may see. Null without `hours::read` and a token covering `api:read:times`.	+1
`tags`	Tags on this project. A project takes at most 50, so this is the whole set.	to-many · +3

Other

trashedstring

Whether soft-deleted rows are included.

withoutdefaultwithonly

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 ProjectList rows.

dataarray of ProjectList

The rows, each a ProjectList.

meta.pagePage

per_page, next_cursor, prev_cursor, total, current_page, last_page.

meta.warningsarray of object

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

linksPageLinks

self, next, prev.

Each row is a ProjectList: 31 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.

titlestring≤ 255

Project title as shown in the UI.

full_titlestring

Application name plus title. Never carries the project number, even when the organisation shows numbers in plnnrly.

descriptionhtml or nullDetail only

Free-text description. HTML from the rich editor, sanitised.

statusstring

Lifecycle status. Setting it to invoiced finishes every task on every budget of the project.

activefinishedinvoicedon-holdinactive

New values may be added.

workflow_modestring or null

Whether work is planned in sprints or on a simple board.

sprintssimple

New values may be added.

start_datedate (YYYY-MM-DD) or null

First day of the project.

end_datedate (YYYY-MM-DD) or null

Last day, null if open-ended.

is_billableboolean

Whether time on this project is billable.

is_continuousboolean

Whether the project has no planned end.

last_activitytimestamp (YYYY-MM-DDThh:mm:ssZ) or null

Most recent write anywhere in the project.

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

Creation timestamp.

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

Last-write timestamp; use for incremental sync.

deleted_attimestamp (YYYY-MM-DDThh:mm:ssZ) or null

Soft-delete timestamp, null while live.

customer_idinteger

Owning customer.

sub_customer_idinteger or null

Optional sub-customer.

project_manager_idinteger or null

Responsible project manager.

account_manager_idinteger or nullServer-assigned

Responsible account manager. Set to the creating user and not writable.

application_idinteger or null

Linked application. Writable only while the organisation has the Infrastructure feature: sending a non-null value without it is a 422 prohibited. Null clears the link regardless.

workflow_idinteger or null

Workflow whose statuses this project's work items move through.

web_urlstring

Absolute URL that opens this project's work 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 to the project page when none of them applies. Read-only.

customerRef or CustomerSummary

Owning customer.

sub_customerRef or CustomerSummary or null

Optional sub-customer.

project_managerRef or UserSummary or null

Responsible project manager.

account_managerRef or UserSummary or null

Responsible account manager.

sprints_countinteger≥ 0

Number of sprints.

budgets_countinteger≥ 0

Number of budgets.

tags_countinteger≥ 0

Number of tags.

tasks_countinteger≥ 0

Number of kanban tasks on this project that the caller may see.

workflow_mode_optionsarray of stringDetail only

Workflow modes this project may switch to. Empty until a workflow is linked.

sprintssimple

New values may be added.

linksProjectLinks

Show 4 child fields

links.selfurl

The canonical URI of this record.

links.tasksurl

Kanban tasks on this project.

links.budgetsurl

Budgets on this project.

links.sprintsurl

Sprints on this project.

tagsarray of TagSummary≤ 50Only with include

Tags on this project. A project takes at most 50 tags, so the include lists them all. tag_ids replaces the whole set.

Wrapped in { data, meta }; meta.truncated says whether the cap was hit and meta.count is the full count.

Show 2 child fields

tags.idinteger

Unique identifier.

tags.titlestring≤ 255

Tag title as shown in the UI.

logged_minutesinteger or nullOn request

Sum of the worklog minutes on this project that the caller may see. Worklogs are per-user unless the caller holds times::update_others or times::delete_others. Null when the caller lacks hours::read or a token covering api:read:times.