Plane API Documentation

Use the Plane API to programmatically read and write changes to your Workspaces, Projects, Work Items, and much more.

info

The Plane Cloud API is available at https://api.plane.so/

Quick Start

1. Get Your API Key

To make requests to the Plane API, you'll need an API key. This key is used to verify your client's identity and permissions. The key must be passed as the value of the X-API-Key header.

Let's get you an API key!

tip

You must have a Plane account or be registered to your instance to generate a key.

1. Log into your Plane account and go to Profile Settings
2. Go to Personal Access Tokens
3. Click Add personal access token
4. Enter a title and description to help you remember why you created this key
5. Optionally set an expiry date for the key, after which the key will no longer be valid

danger

Treat your API key like a password. Keep it secret. Keep it safe. Store your API key securely and keep it confidential to prevent unauthorized access to your account. Do not share it or expose it in client-side code.

2. Execute an HTTP Request 🔄

When issuing HTTP requests to the API, always set the X-API-Key request header to your API key. For example, using curl:

curl -L 'https://api.plane.so/api/v1/workspaces/:slug/projects/:project_id/issues/' \
-H 'Accept: application/json' \
-H 'X-API-Key: <X-API-Key>'

Run the above command to receive your first response from the Plane API.

3. Congratulations 🥳

Congratulations! You've successfully run your first HTTP request using the Plane API. Next, browse the rest of our documentation for more examples of how you can integrate your project! 😎

---

General API Usage

Base URL

All requests to the Plane Cloud API must be made to the following base URL:

https://api.plane.so/

info

If you're using a self-hosted instance of Plane, your API base URL will differ based on your custom domain and setup.

Security Recommendations

• Keep the API Key Secret: Treat your API key like a password. Do not share it or expose it in client-side code.
• Regenerate Key If Compromised: If you suspect that your API key has been compromised, generate a new one immediately and update your applications.

API Key Errors

• If the X-API-Key header is not included, the API will return an error indicating that authentication is required.
• If the provided API key is invalid or expired, the API will return an error message indicating an authentication failure.

HTTP Methods

HTTP defines a set of request methods, also known as HTTP verbs, to indicate the desired action for a given resource.

Below is a list of methods commonly adopted by Plane's API:

Verb	Description	Example
GET	Requests a representation of the specified resource	Fetch all work items from a project
POST	Submits an entity to the specified resource	Create a project
DELETE	Deletes the specified resource	Delete a work item
PATCH	Applies partial modifications to a resource	Edit a module

Status Codes

Below are the most commonly encountered success responses:

Status Code	Description
200 OK	The request succeeded. Generally used in GET or PATCH requests.
201 Created	The request succeeded and a new resource was created. Generally used in POST requests.
204 No Content	The request succeeded and no body is returned. Generally used in DELETE requests.

Error Responses

Below are the most commonly encountered error responses:

Status Code	Description
400 Bad Request	The server cannot or will not process the request due to something that is perceived to be a client error.
401 Unauthorized	Although the HTTP standard specifies "unauthorized", semantically, this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
404 Not Found	The server cannot find the requested resource. This means the URL is not recognized.
429 Throttling Error	The server has received too many requests from your client within a short period of time. Retry the request later. You can read more in our rate-limiting section.
500 Internal Server Error	The server has encountered a situation it does not know how to handle, and failed to process the request.
502 Bad Gateway	The server received an invalid response from another service which was required to handle the request.
503 Service Unavailable	The server is not ready to handle the request. Common causes are a server that is down for maintenance or overloaded.
504 Gateway Timeout	The server was unable to receive a timely response from a downstream service.

---

Pagination

The Plane API implements a cursor-based pagination system, allowing clients to efficiently navigate through large datasets. The system uses a cursor parameter to manage the position and direction of pagination.

Query String Parameters

Paging is controlled by clients via the following query string parameters:

• per_page (optional): Number of items to display per page. Defaults to 100. The maximum allowed value is 100.
• cursor (optional): Cursor string (see below) to navigate to a specific page. If not provided, pagination starts from the first page.

Cursor String Format

The cursor string is formatted as value:offset:is_prev, where:

• value represents the page size (number of items per page)
• offset is the current page number (starting from 0)
• is_prev indicates whether the cursor is moving to the previous page (1) or to the next page (0)

Example: Fetching the First Page

GET /api/v1/workspaces/:workspace-slug/projects/:project_id/issues/?per_page=20

Pagination Response

The paginated response includes the following fields:

• next_cursor: Cursor string for the next page
• prev_cursor: Cursor string for the previous page
• next_page_results: Boolean indicating if there are more results after the current page
• prev_page_results: Boolean indicating if there are results before the current page
• count: Total number of items on the current page
• total_pages: Estimated total number of pages
• total_results: Total number of items across all pages
• extra_stats: Additional statistics, if any
• results: Array of items for the current page

Here's an example response for the first page of results:

{
  "next_cursor": "20:1:0",
  "prev_cursor": "",
  "next_page_results": true,
  "prev_page_results": false,
  "count": 20,
  "total_pages": 50,
  "total_results": 1000,
  "extra_stats": {},
  "results": [ ... items ... ]
}

Example: Fetching the Next Page

GET /api/v1/workspaces/:workspace-slug/projects/:project_id/issues?per_page=20&cursor=20:1:0

Pagination Next Page Response

{
  "next_cursor": "20:2:0",
  "prev_cursor": "20:0:1",
  "next_page_results": true,
  "prev_page_results": true,
  "count": 20,
  "total_pages": 50,
  "total_results": 1000,
  "extra_stats": {},
  "results": [ ... items ... ]
}

Pagination Errors

• Invalid Cursor Format: If the provided cursor string is not in the correct format, the API will respond with an error message indicating an invalid cursor format.
• Pagination Limits: Requests exceeding the maximum per_page limit will receive an error response detailing the maximum allowed value.

---

Rate Limiting

To ensure fair usage and maintain the overall quality of service for the community, the Plane API implements rate limiting. Rate limiting restricts the number of requests a client can make within a certain time frame.

Rate Limit Details

• Limit: Each client is limited to 60 requests per minute
• Reset Interval: The rate limit counter resets every minute
• Scope of Limitation: The rate limit applies to all requests made with a given API key

Identifying Your Rate Limit Status

Your current rate limit status is communicated in the response headers of each API request:

• X-RateLimit-Remaining: The number of requests remaining in the current rate limit window
• X-RateLimit-Reset: The time at which the current rate limit window resets (in UTC epoch seconds)

X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1700327957

---

Fine-Tuning Response Fields

The Plane API provides flexible data retrieval capabilities through two powerful query parameters: fields and expand. These parameters allow clients to tailor the response data to their specific needs, optimizing both the payload size and the clarity of the response.

Fields Parameter

The fields parameter enables clients to selectively retrieve only a subset of fields for a given resource.

tip

The fields parameter is particularly useful for reducing response time, size, and bandwidth, especially when your client requires only specific pieces of data.

The fields parameter accepts a comma-separated list of field names that the client wants to be included in the response. For example, to include only the id, name, and description fields, send the following query string parameters:

GET /api/v1/workspaces/:workspace-slug/projects/:project_id/issues/?fields=id,name,description

Fields Parameter Error Handling

Invalid or unrecognized field names passed in the fields parameter will result in an error response, indicating which fields are invalid.

Expand Parameter

The expand parameter allows clients to request additional related information to be included in the response. This is useful for retrieving detailed information about nested resources without making separate API calls.

For example, to return the resource data along with expanded information about the assignees and state, send the following query string parameters:

GET /api/v1/workspaces/:workspace-slug/projects/:project_id/issues/?expand=assignees,state

Expand Parameter Error Handling

If expand is used on fields that cannot be expanded, an appropriate error message will be returned.