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

string

required

Workspace slug identifier

uuid

required

Project UUID

Query Parameters

string

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

string

Search term to filter work items

uuid

Filter by state ID

integer

default:"100"

Number of items per page

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": "john@example.com",
        "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

string

required

Workspace slug identifier

uuid

required

Project UUID

Request Body

string

required

Work item title/name

string

HTML-formatted description (sanitized for security)

string

Binary description data (validated)

uuid

required

State ID (must belong to the project)

string

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

array

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

array

Array of label IDs (must belong to the project)

date

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

date

Target/due date (YYYY-MM-DD)

uuid

Parent issue ID for sub-issues

uuid

Estimate point ID for story points

uuid

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

string

External integration source identifier

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

string

required

Workspace slug identifier

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

string

required

HTML-formatted comment (sanitized)

object

JSON representation of comment

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

string

required

Link title/description

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

string

required

Original filename

integer

required

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

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

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"
}

​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

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