How the data fits together

This page maps the resources the API exposes and how they point at each other. Read it before you design a sync or a report, so you know which collection holds what. Each resource name links to its schema page, which lists every field.

Paths on this page are relative to https://<your-url>/api/v2. <your-url> is the address you sign in to plnnrly on, such as acme.plnnrly.com, or your organisation's own domain.

One organisation per host

Everything you read or write belongs to one organisation, and the host decides which one. A token works only on the host of the organisation it was created in.

Ids are unique per resource inside an organisation, not across resources and not across organisations. Project 12 and work item 12 are different records, and so are project 12 in one organisation and project 12 in another. Key your copy on the resource and the id together, and add the host if your integration serves several organisations.

GET / lists the resources your organisation has, with their paths. See Discovery.

Projects and work

A project belongs to a customer. It has a project manager, an account manager, tags, and a workflow mode that decides whether its work is planned in sprints or on a simple board.

The issue key is built from the customer's code and a running number, so ACM-12 is a work item on a project of the customer with code ACM. Every work item path accepts the issue key in place of the numeric id.

Time

Both collections return only your own rows unless you name other users. See Filters that default to you.

Drive

Drive items, folders and documents live in a drive, and a drive belongs to an owner: a project, a customer, the organisation, or one user. For those, the owner type decides which permission and which token scope apply. Notes need a drive scope in your token, but the record a note is attached to decides whether you may read or write it. Todos need the project_management grant. See Scopes and permissions.

Drive items also have comments and files, under /drive-items/{drive_item}/comments and /drive-items/{drive_item}/files.

Customers

Billing

Leave

Planning

An event is one block on a user's agenda, at /events. It can point at a kanban task, so time can be logged against it. A recurring series is one event with recurrence fields. Its occurrences are not records of their own, unless one was split off from the series in plnnrly.

Like worklogs and timers, /events returns only your own rows unless you name other users.

Organisation

The API does not create, change or delete users. Roles, permissions and teams are not in the API at all.

Configuration

Changing a work item's status is an action, not a field write. See Actions and state changes.

How records point at each other

A record points at another through a foreign key, usually named after the relation, with the related record next to it. On a work item row from GET /work-items:

{
  "sprint_id": 31,
  "sprint": { "id": 31 }
  // 33 more fields: id, issue_key, title, priority, due_date, estimation, remaining_estimate, order, column_order, version, created_at, updated_at, project_id, task_id, workflow_status_id, work_type_id, parent_id, assignee_id, reporter_id, web_url, workflow_status, parent, assignee, reporter, work_type, comments_count, subtasks_count, attachments_count, child_work_items_count, labels_count, drive_items_count, links_count, links
}

The related record stays a bare {"id": …} until you name it in include. A few relations are always filled in, such as the customer on a project. See Views and includes.

Some fields can point at one of several kinds of record. They come as a {name}_type and {name}_id pair, plus the record itself. A Drive item's owner, for example:

{
  "owner_type": "project",
  "owner_id": 12,
  "owner": { "id": 12 }
  // 23 more fields: id, title, group, kind, source, folder_id, drive_folder, content_record_type, content_record_id, content_record, order_column, created_by, archived_by, inherits_permissions, general_access, access, created_at, updated_at, deleted_at, comments_count, files_count, tags_count, links
}

The type is always a short name, such as project, customer, organization, user, work_item or event, never an internal class name. The schema page of each resource lists the names its fields can hold. To filter on such a pair, send both halves; see Paired filters.

Areas your organisation may not have

Two areas exist only when your organisation has the feature behind them:

Sprints and work items are always there, with or without the sprints feature.

Without the feature, every operation in that area answers 404 endpoint-not-found, and GET / does not list it. Call GET / first if your integration has to work for more than one organisation.

The MCP & API switches that turn the whole API on or off are a separate thing. See For administrators.

Related

• Data formats: how dates, money, durations and empty values are written.
• Views and includes: how much of each record you get back.
• Scopes and permissions: which grant each area needs.