Plane API v2

API v2 is the current version of the Plane REST API. It is resource-oriented, accepts JSON request bodies, and returns JSON responses.

API v1 remains available for existing integrations. Use the API version switcher at the top of the sidebar to move between the two references.

Base URL

Deployment	Base URL
Plane Cloud	https://api.plane.so
Self-hosted	Your instance URL, for example https://plane.example.com

Every v2 path lives under /api/v2/ and ends with a trailing slash: /api/v2/users/me/, not /api/v2/users/me.

Authentication

Send an API key in the X-Api-Key header of every request. Keys are personal access tokens, created under Profile Settings → Personal Access Tokens — see Generating an API key.

First request

GET /api/v2/users/me/ needs no workspace or project, which makes it the quickest way to check that your key works.

curl "https://api.plane.so/api/v2/users/me/" \
  -H "X-Api-Key: $PLANE_API_KEY"

A 200 response means the key is valid. A 401 means the header is missing or the key is wrong.

Machine-readable schema

The full OpenAPI document is served live at:

GET /api/v2/schema/

Point a generator at it to produce a typed client, or diff it between releases to see exactly what changed.

Where to go next

• Authentication — API keys, OAuth 2.0, and the scope model.
• Pagination — offset by default, cursor for deep traversal.
• Filtering and ordering — query parameters on list endpoints.
• Sparse fields — trim responses to the fields you need with ?fields=.
• Expanding relations — where ?expand= works and what it accepts.
• Errors — the RFC 9457 problem shape and the full code table.
• Migrating from v1 — what changed and how to move.