Plane API

Welcome to the Plane API documentation. The Plane API provides a comprehensive REST interface to interact with your Plane workspace programmatically.

Base URL

All API requests are made to:

https://your-instance.plane.so/api/v1/

For self-hosted instances, replace your-instance.plane.so with your domain.

API Versioning

The current API version is v1. The version is included in the URL path:

Production API: /api/v1/
Legacy API: /api/ (deprecated)

Request Format

The Plane API accepts JSON-encoded request bodies. All requests must include the following headers:

Content-Type: application/json
X-Api-Key: your_api_key_here

Response Format

All responses are returned as JSON. Successful responses return a 200 or 201 status code along with the requested data.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Example Project",
  "created_at": "2024-03-09T10:30:00Z"
}

Error Handling

Errors are returned with appropriate HTTP status codes and a JSON body:

{
  "error": "Invalid request",
  "detail": "Project Identifier is required"
}

Common Error Codes

Status Code	Description
`400`	Bad Request - Invalid parameters or validation error
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource does not exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong

Rate Limiting

API requests are rate-limited to ensure fair usage and system stability.

Default Limits

API Key: 60 requests per minute (configurable via API_KEY_RATE_LIMIT)
Service Token: 300 requests per minute

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1678356000

Number of requests remaining in the current window

Unix timestamp when the rate limit resets

Handling Rate Limits

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response:

{
  "error": "Request was throttled. Expected available in 45 seconds."
}

Implement exponential backoff in your application to handle rate limits gracefully.

Pagination

List endpoints support pagination to manage large datasets. Use the following query parameters:

integer

default:"100"

Number of items to return per page (max: 100)

integer

default:"0"

Number of items to skip

Example

curl -X GET "https://api.plane.so/api/v1/workspaces/acme/projects/?limit=20&offset=40" \
  -H "X-Api-Key: your_api_key"

Filtering and Sorting

Many list endpoints support filtering and sorting:

string

Search term to filter results

string

Field name to sort by (prefix with - for descending)

Example

curl -X GET "https://api.plane.so/api/v1/workspaces/acme/projects/?search=frontend&ordering=-created_at" \
  -H "X-Api-Key: your_api_key"

Field Expansion

Some endpoints support field expansion to include related objects in the response:

string

Comma-separated list of fields to expand (e.g., assignees,labels)

Example

curl -X GET "https://api.plane.so/api/v1/workspaces/acme/projects/proj-123/work-items/?expand=assignees,labels" \
  -H "X-Api-Key: your_api_key"

Timestamps

All timestamps are returned in ISO 8601 format with UTC timezone:

"created_at": "2024-03-09T10:30:00.000000Z"

UUIDs

Plane uses UUIDs (v4) for resource identifiers:

"id": "550e8400-e29b-41d4-a716-446655440000"

Next Steps

Authentication

Learn how to authenticate your API requests

Work Items

Manage issues and tasks in your projects

Projects

Create and manage projects

Workspaces

Access workspace information

Overview

Endpoints

API Introduction

Plane API

Base URL

API Versioning

Request Format

Response Format

Error Handling

Common Error Codes

Rate Limiting

Default Limits

Rate Limit Headers

Handling Rate Limits

Example

Filtering and Sorting

Example

Field Expansion

Example

Timestamps

UUIDs

Next Steps

Authentication

Work Items

Projects

Workspaces

​Plane API

​Base URL

​API Versioning

​Request Format

​Response Format

​Error Handling

​Common Error Codes

​Rate Limiting

​Default Limits

​Rate Limit Headers

​Handling Rate Limits

​Pagination

​Example

​Filtering and Sorting

​Example

​Field Expansion

​Example

​Timestamps

​UUIDs

​Next Steps

Authentication

Work Items

Projects

Workspaces

Plane API

Base URL

API Versioning

Request Format

Response Format

Error Handling

Common Error Codes

Rate Limiting

Default Limits

Rate Limit Headers

Handling Rate Limits

Pagination

Example

Filtering and Sorting

Example

Field Expansion

Example

Timestamps

UUIDs

Next Steps