# Guides

How the REST API behaves across every operation, written once so the operation pages do not have to repeat it.

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](https://developers.plnnrly.com/en/docs/api/v2/guides/getting-started/). The other guides answer questions as they come up.

- [Getting started](https://developers.plnnrly.com/en/docs/api/v2/guides/getting-started/): Create a token, find your address, then make your first reads and your first write, one step at a time.
- [Authentication](https://developers.plnnrly.com/en/docs/api/v2/guides/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](https://developers.plnnrly.com/en/docs/api/v2/guides/oauth-apps/): 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](https://developers.plnnrly.com/en/docs/api/v2/guides/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](https://developers.plnnrly.com/en/docs/api/v2/guides/scopes/): 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.
- [How the data fits together](https://developers.plnnrly.com/en/docs/api/v2/guides/data-model/): A map of the resources behind the API, how they relate, and which areas exist only when your organisation has them.
- [Data formats](https://developers.plnnrly.com/en/docs/api/v2/guides/data-formats/): How the API writes dates, times, durations, money, ids, enums and empty values, and the forms it accepts back.
- [Pagination](https://developers.plnnrly.com/en/docs/api/v2/guides/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](https://developers.plnnrly.com/en/docs/api/v2/guides/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](https://developers.plnnrly.com/en/docs/api/v2/guides/views-and-includes/): Choose a field set with view, inline related records and on-demand fields with include, and read meta.actions and warnings.
- [Concurrency and ETags](https://developers.plnnrly.com/en/docs/api/v2/guides/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](https://developers.plnnrly.com/en/docs/api/v2/guides/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](https://developers.plnnrly.com/en/docs/api/v2/guides/actions/): 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](https://developers.plnnrly.com/en/docs/api/v2/guides/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](https://developers.plnnrly.com/en/docs/api/v2/guides/uploads/): Attach a file to a work item or a Drive item in three steps, and download attached files through a signed link.
- [Rate limits](https://developers.plnnrly.com/en/docs/api/v2/guides/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](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/): 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](https://developers.plnnrly.com/en/docs/api/v2/guides/limits/): 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](https://developers.plnnrly.com/en/docs/api/v2/guides/syncing-data/): 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](https://developers.plnnrly.com/en/docs/api/v2/guides/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](https://developers.plnnrly.com/en/docs/api/v2/guides/known-limitations/): The things the REST API does not offer today, each with the page that explains it or the way around it.
- [Generating a client](https://developers.plnnrly.com/en/docs/api/v2/guides/client-generation/): Generate a client or import the API into an API tool from /openapi.json, and avoid the traps that break generated clients.
- [Recipes](https://developers.plnnrly.com/en/docs/api/v2/guides/recipes/): Worked examples that combine several requests into one task.