API Introduction

Learn how to use the Plane REST API to build integrations and automate your project management workflows

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

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