Intro to Plane API

Video Placeholder Duration: 5-7 minutes Topics covered: API overview, authentication, endpoints, examples, webhooks

What is the Plane API?

The Plane API provides programmatic access to your Plane data. Build custom integrations, automate workflows, create dashboards, and connect Plane to any system.

API Capabilities

With the API you can:

Read and create work items
Manage projects and cycles
Update states and properties
Query and filter data
Build custom applications
Automate workflows

Authentication

API Tokens

Go to Profile Settings → API Tokens
Click Create Token
Give it a name and set scope
Copy the token (shown only once)

Using the Token

Include in request headers:

Authorization: Bearer YOUR_API_TOKEN

Token Security

Never commit tokens to code
Use environment variables
Rotate tokens periodically
Use minimal required scopes

Base URL

Plane Cloud

https://api.plane.so/v1/

Self-Hosted

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

Common Endpoints

Work Items (Issues)

List work items:

GET /workspaces/{workspace_slug}/projects/{project_id}/issues/

Get single item:

GET /workspaces/{workspace_slug}/projects/{project_id}/issues/{issue_id}/

Create item:

POST /workspaces/{workspace_slug}/projects/{project_id}/issues/

Update item:

PATCH /workspaces/{workspace_slug}/projects/{project_id}/issues/{issue_id}/

Projects

List projects:

GET /workspaces/{workspace_slug}/projects/

Get project:

GET /workspaces/{workspace_slug}/projects/{project_id}/

Cycles

List cycles:

GET /workspaces/{workspace_slug}/projects/{project_id}/cycles/

Request Examples

List Work Items (curl)

bash

curl -X GET \
  "https://api.plane.so/v1/workspaces/my-workspace/projects/abc123/issues/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

Create Work Item (curl)

bash

curl -X POST \
  "https://api.plane.so/v1/workspaces/my-workspace/projects/abc123/issues/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fix login timeout",
    "description": "Users experiencing timeout on login page",
    "priority": "high",
    "state": "state-uuid"
  }'

Update Work Item (curl)

bash

curl -X PATCH \
  "https://api.plane.so/v1/workspaces/my-workspace/projects/abc123/issues/issue-uuid/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "in-progress-state-uuid"
  }'

JavaScript Example

javascript

const PLANE_TOKEN = process.env.PLANE_TOKEN;
const BASE_URL = 'https://api.plane.so/v1';
const WORKSPACE = 'my-workspace';
const PROJECT = 'project-id';

// List work items
async function getIssues() {
  const response = await fetch(
    `${BASE_URL}/workspaces/${WORKSPACE}/projects/${PROJECT}/issues/`,
    {
      headers: {
        'Authorization': `Bearer ${PLANE_TOKEN}`,
        'Content-Type': 'application/json'
      }
    }
  );
  return response.json();
}

// Create work item
async function createIssue(title, description) {
  const response = await fetch(
    `${BASE_URL}/workspaces/${WORKSPACE}/projects/${PROJECT}/issues/`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${PLANE_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: title,
        description: description
      })
    }
  );
  return response.json();
}

Python Example

python

import requests
import os

PLANE_TOKEN = os.environ['PLANE_TOKEN']
BASE_URL = 'https://api.plane.so/v1'
WORKSPACE = 'my-workspace'
PROJECT = 'project-id'

headers = {
    'Authorization': f'Bearer {PLANE_TOKEN}',
    'Content-Type': 'application/json'
}

# List work items
def get_issues():
    url = f'{BASE_URL}/workspaces/{WORKSPACE}/projects/{PROJECT}/issues/'
    response = requests.get(url, headers=headers)
    return response.json()

# Create work item
def create_issue(title, description):
    url = f'{BASE_URL}/workspaces/{WORKSPACE}/projects/{PROJECT}/issues/'
    data = {
        'name': title,
        'description': description
    }
    response = requests.post(url, headers=headers, json=data)
    return response.json()

Webhooks

What are Webhooks?

Webhooks notify your systems when events happen in Plane.

Setting Up

Go to Workspace Settings → Webhooks
Click Create Webhook
Enter your endpoint URL
Select events to trigger on
Save

Available Events

Work item created/updated/deleted
Comment added
State changed
Assignee changed
Cycle events
Project events

Webhook Payload

json

{
  "event": "issue.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "issue-uuid",
    "name": "New work item",
    "project": "project-uuid",
    "state": "state-uuid",
    ...
  }
}

Rate Limiting

Limits

API requests are rate-limited to prevent abuse.

Headers

Check rate limit status in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705312800

Best Practices

Cache responses when possible
Use webhooks instead of polling
Implement exponential backoff

Error Handling

Common Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Rate Limited
500	Server Error

Error Response

json

{
  "error": "Invalid request",
  "detail": "Field 'name' is required"
}

Best Practices

Security

Use environment variables for tokens
Implement proper error handling
Log API interactions

Performance

Use pagination for large datasets
Cache where appropriate
Batch requests when possible

Reliability

Handle rate limits gracefully
Implement retries with backoff
Validate webhook signatures

Key Takeaways

Plane API provides programmatic access to your data
Authenticate with API tokens
RESTful endpoints for work items, projects, cycles
Webhooks for real-time event notifications
Available in any language that makes HTTP requests
Follow rate limiting and security best practices

Course Complete!

Congratulations! You've completed Plane 202 — The Power Relay. You now understand:

Plane Sites for public publishing
Customer tracking and management
Slack, GitHub, and GitLab integrations
Plane Apps ecosystem
Compose for content generation
CLI for terminal workflows
API for custom integrations

What's Next?

Learn about Plane deployment options:

Next Course: Plane 301 — The Setup

Intro to Plane API ​

What is the Plane API? ​

API Capabilities ​

Authentication ​

API Tokens ​

Using the Token ​

Token Security ​

Base URL ​

Plane Cloud ​

Self-Hosted ​

Common Endpoints ​

Work Items (Issues) ​

Projects ​

Cycles ​

Request Examples ​

List Work Items (curl) ​

Create Work Item (curl) ​

Update Work Item (curl) ​

JavaScript Example ​

Python Example ​

Webhooks ​

What are Webhooks? ​

Setting Up ​

Available Events ​

Webhook Payload ​

Rate Limiting ​

Limits ​

Headers ​

Best Practices ​

Error Handling ​

Common Status Codes ​

Error Response ​

Best Practices ​

Security ​

Performance ​

Reliability ​

Key Takeaways ​

Course Complete! ​

What's Next? ​

Intro to Plane API

What is the Plane API?

API Capabilities

Authentication

API Tokens

Using the Token

Token Security

Base URL

Plane Cloud

Self-Hosted

Common Endpoints

Work Items (Issues)

Projects

Cycles

Request Examples

List Work Items (curl)

Create Work Item (curl)

Update Work Item (curl)

JavaScript Example

Python Example

Webhooks

What are Webhooks?

Setting Up

Available Events

Webhook Payload

Rate Limiting

Limits

Headers

Best Practices

Error Handling

Common Status Codes

Error Response

Best Practices

Security

Performance

Reliability

Key Takeaways

Course Complete!

What's Next?