These guides cover what is true for every operation: tokens, paging, errors, retries and the rest. An operation page states only what is specific to that request, such as its scope, its permission and its parameters, and links here for everything else.
New to the API? Start with Getting started. The other guides answer questions as they come up.
Start
- Getting started
Create a token, find your address, then make your first reads and your first write, one step at a time.
- Authentication
Every request carries a bearer token, sent to your organisation's own address and acting as one user. Here is how it works and how it fails.
- Sign in with OAuth
Let people sign in to your desktop or command-line app with their plnnrly account, instead of pasting a token. OAuth 2.0 with PKCE, step by step.
- API tokens
Create the personal access tokens your scripts and integrations use, narrow them to what they need, and roll or revoke them in time.
- Scopes and permissions
Every operation needs a token scope and a permission on the user's role. How both are built, what each covers and which one to fix when a call is refused.
Reading data
- How the data fits together
A map of the resources behind the API, how they relate, and which areas exist only when your organisation has them.
- Data formats
How the API writes dates, times, durations, money, ids, enums and empty values, and the forms it accepts back.
- Pagination
Cursor paging by default, page numbers on collections that count their rows, page sizes, totals, and how to walk a whole collection.
- Filtering and sorting
Narrow a collection with bracket filters and operators, search it with q, order it with sort, and read soft-deleted rows.
- Views and includes
Choose a field set with view, inline related records and on-demand fields with include, and read meta.actions and warnings.
Writing data
- Concurrency and ETags
Use ETags to skip re-reading data that has not changed, and to stop a write from overwriting a change you have not seen.
- Idempotency
Send an Idempotency-Key with a POST, so that a retry after a lost response returns the first result instead of writing twice.
- Actions and state changes
How the action endpoints work, which ones you may call on a record, how to make them safe to retry, and what each outcome means.
- Deleting and restoring
What a DELETE does to each resource, how to read and restore archived records, what can block a delete and who may delete.
- Files: upload and download
Attach a file to a work item or a Drive item in three steps, and download attached files through a signed link.
In production
- Rate limits
What each request costs, the ceilings per token and per organisation, and the headers that tell you how much budget is left.
- Errors and retries
Every failure is a problem document. Switch on the problem type, never on the status code alone, and retry only what is safe to retry.
- Limits at a glance
Every numeric limit of the REST API and the MCP server in one place, with a link to the guide that explains each one.
- Keeping a copy in sync
plnnrly has no webhooks. Poll each collection from a high-water mark on updated_at, re-check cheaply, and catch deleted records.
- Headers and versioning
The request headers you may send, the response headers you get back, and how the API changes within v2.
- What the API cannot do
The things the REST API does not offer today, each with the page that explains it or the way around it.
- Generating a client
Generate a client or import the API into an API tool from /openapi.json, and avoid the traps that break generated clients.
Recipes
- Recipes
Worked examples that combine several requests into one task.