Skip to main content

​
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 CodeDescription
400Bad Request - Invalid parameters or validation error
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource does not exist
429Too Many Requests - Rate limit exceeded
500Internal 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
​
X-RateLimit-Remaining
Number of requests remaining in the current window
​
X-RateLimit-Reset
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:
​
limit
integer
default:"100"
Number of items to return per page (max: 100)
​
offset
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:
​
search
string
Search term to filter results
​
ordering
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:
​
expand
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

Build docs developers (and LLMs) love

Get started for freeTalk to us