Work Items API

Work items (also known as issues) are the core building blocks of project management in Plane. This API allows you to manage issues, their relationships, comments, attachments, and activities.

Endpoints

List Work Items

GET

Retrieve a list of work items in a project.

Path Parameters

slug

string

required

Workspace slug identifier

project_id

uuid

required

Project UUID

Query Parameters

expand

string

Comma-separated fields to expand: assignees, labels, state, cycle, module

string

Search term to filter work items

state

uuid

Filter by state ID

limit

integer

default:"100"

Number of items per page

offset

integer

default:"0"

Number of items to skip

Example Request

curl -X GET "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/work-items/?expand=assignees,labels" \
  -H "X-Api-Key: your_api_key"

Response

[
  {
    "id": "650e8400-e29b-41d4-a716-446655440000",
    "name": "Fix authentication bug",
    "description_html": "<p>Users unable to log in with SSO</p>",
    "sequence_id": 42,
    "state": "450e8400-e29b-41d4-a716-446655440000",
    "priority": "high",
    "assignees": [
      {
        "id": "350e8400-e29b-41d4-a716-446655440000",
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "avatar_url": "https://example.com/avatar.jpg"
      }
    ],
    "labels": [
      {
        "id": "250e8400-e29b-41d4-a716-446655440000",
        "name": "bug",
        "color": "#FF0000"
      }
    ],
    "start_date": "2024-03-01",
    "target_date": "2024-03-15",
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "workspace_id": "750e8400-e29b-41d4-a716-446655440000",
    "created_by": "350e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-03-01T10:00:00Z",
    "updated_at": "2024-03-09T14:30:00Z"
  }
]

Create Work Item

POST

Create a new work item in a project.

Path Parameters

slug

string

required

Workspace slug identifier

project_id

uuid

required

Project UUID

Request Body

name

string

required

Work item title/name

description_html

string

HTML-formatted description (sanitized for security)

description_binary

string

Binary description data (validated)

state

uuid

required

State ID (must belong to the project)

priority

string

Priority level: urgent, high, medium, low, none

assignees

array

Array of user IDs to assign (must be project members with role ≥ 15)

labels

array

Array of label IDs (must belong to the project)

start_date

date

Start date (YYYY-MM-DD). Cannot exceed target_date

target_date

date

Target/due date (YYYY-MM-DD)

parent

uuid

Parent issue ID for sub-issues

estimate_point

uuid

Estimate point ID for story points

type_id

uuid

Issue type ID (defaults to project’s default type)

external_source

string

External integration source identifier

external_id

string

External system identifier for tracking

Example Request

curl -X POST "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/work-items/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Implement user authentication",
    "description_html": "<p>Add OAuth 2.0 authentication flow</p>",
    "state": "450e8400-e29b-41d4-a716-446655440000",
    "priority": "high",
    "assignees": ["350e8400-e29b-41d4-a716-446655440000"],
    "labels": ["250e8400-e29b-41d4-a716-446655440000"],
    "start_date": "2024-03-10",
    "target_date": "2024-03-20"
  }'

Response

{
  "id": "650e8400-e29b-41d4-a716-446655440000",
  "name": "Implement user authentication",
  "description_html": "<p>Add OAuth 2.0 authentication flow</p>",
  "sequence_id": 43,
  "state": "450e8400-e29b-41d4-a716-446655440000",
  "priority": "high",
  "assignees": ["350e8400-e29b-41d4-a716-446655440000"],
  "labels": ["250e8400-e29b-41d4-a716-446655440000"],
  "start_date": "2024-03-10",
  "target_date": "2024-03-20",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "750e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-03-09T15:00:00Z",
  "updated_at": "2024-03-09T15:00:00Z"
}

Get Work Item

GET

Retrieve a specific work item by ID.

Path Parameters

slug

string

required

Workspace slug identifier

project_id

uuid

required

Project UUID

uuid

required

Work item UUID

Example Request

curl -X GET "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/work-items/650e8400-e29b-41d4-a716-446655440000/" \
  -H "X-Api-Key: your_api_key"

Update Work Item

PATCH

Update a work item’s properties.

Request Body

All fields from the create endpoint are supported. Only include fields you want to update.

Example Request

curl -X PATCH "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/work-items/650e8400-e29b-41d4-a716-446655440000/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "850e8400-e29b-41d4-a716-446655440000",
    "priority": "urgent"
  }'

Delete Work Item

DELETE

Delete a work item.

Example Request

curl -X DELETE "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/work-items/650e8400-e29b-41d4-a716-446655440000/" \
  -H "X-Api-Key: your_api_key"

Work Item Comments

List Comments

GET

Create Comment

POST

Request Body

comment_html

string

required

HTML-formatted comment (sanitized)

comment_json

object

JSON representation of comment

access

string

default:"internal"

Access level: internal, external

Example Request

curl -X POST "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/work-items/650e8400-e29b-41d4-a716-446655440000/comments/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "comment_html": "<p>This looks good to me!</p>",
    "access": "internal"
  }'

Work Item Links

Create Link

POST

Request Body

title

string

required

Link title/description

url

string

required

Valid HTTP/HTTPS URL

Example Request

curl -X POST "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/work-items/650e8400-e29b-41d4-a716-446655440000/links/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Design mockups",
    "url": "https://figma.com/file/abc123"
  }'

Work Item Attachments

Upload Attachment

POST

Request Body

name

string

required

Original filename

size

integer

required

File size in bytes (max: 5MB by default)

type

string

MIME type of the file

Work Item Activities

List Activities

GET

Retrieve the activity history for a work item.

Search Work Items

GET

Search for work items across a workspace.

Query Parameters

string

required

Search query

project_id

uuid

Filter by specific project

Example Request

curl -X GET "https://api.plane.so/api/v1/workspaces/acme/work-items/search/?q=authentication" \
  -H "X-Api-Key: your_api_key"

Get Work Item by Identifier

GET

Retrieve a work item using the human-readable identifier (e.g., PROJ-42).

Example Request

curl -X GET "https://api.plane.so/api/v1/workspaces/acme/work-items/ACME-42/" \
  -H "X-Api-Key: your_api_key"

Validation Rules

HTML Content: All HTML fields are sanitized for XSS prevention
Date Range: start_date cannot exceed target_date
Assignees: Must be active project members with role ≥ 15
Labels: Must belong to the same project
State: Must belong to the same project
Parent: Must be an issue in the same project and workspace
Estimate Point: Must belong to the same project and workspace

Error Responses

Validation Error

{
  "error": "Start date cannot exceed target date"
}

Invalid HTML

{
  "error": "html content is not valid"
}

Invalid State

{
  "error": "State is not valid please pass a valid state_id"
}

Overview

Endpoints

​Work Items API

​Endpoints

​List Work Items

​Path Parameters

​Query Parameters

​Example Request

​Response

​Create Work Item

​Path Parameters

​Request Body

​Example Request

​Response

​Get Work Item

​Path Parameters

​Example Request

​Update Work Item

​Request Body

​Example Request

​Delete Work Item

​Example Request

​Work Item Comments

​List Comments

​Create Comment

​Request Body

​Example Request

​Work Item Links

​Create Link

​Request Body

​Example Request

​Work Item Attachments

​Upload Attachment

​Request Body

​Work Item Activities

​List Activities

​Search Work Items

​Query Parameters

​Example Request

​Get Work Item by Identifier

​Example Request

​Validation Rules

​Error Responses

​Validation Error

​Invalid HTML

​Invalid State

Build docs developers (and LLMs) love

Work Items API

Endpoints

List Work Items

Path Parameters

Query Parameters

Example Request

Response

Create Work Item

Path Parameters

Request Body

Example Request

Response

Get Work Item

Path Parameters

Example Request

Update Work Item

Request Body

Example Request

Delete Work Item

Example Request

Work Item Comments

List Comments

Create Comment

Request Body

Example Request

Work Item Links

Create Link

Request Body

Example Request

Work Item Attachments

Upload Attachment

Request Body

Work Item Activities

List Activities

Search Work Items

Query Parameters

Example Request

Get Work Item by Identifier

Example Request

Validation Rules

Error Responses

Validation Error

Invalid HTML

Invalid State