Projects API

Projects are the primary organizational unit in Plane. This API allows you to create, retrieve, update, and delete projects within a workspace.

Endpoints

List Projects

GET

Retrieve all projects in a workspace.

Path Parameters

slug

string

required

Workspace slug identifier

Query Parameters

string

Search term to filter projects

ordering

string

Sort field (prefix with - for descending): name, created_at, updated_at

Example Request

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

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Mobile App",
    "identifier": "MOBILE",
    "description": "iOS and Android mobile application",
    "logo_props": {
      "in_use": "icon",
      "icon": {
        "name": "rocket",
        "color": "#5e6ad2"
      }
    },
    "cover_image": "https://example.com/cover.jpg",
    "cover_image_url": "https://example.com/cover.jpg",
    "workspace_id": "750e8400-e29b-41d4-a716-446655440000",
    "project_lead": "350e8400-e29b-41d4-a716-446655440000",
    "default_assignee": "350e8400-e29b-41d4-a716-446655440000",
    "total_members": 12,
    "total_cycles": 5,
    "total_modules": 8,
    "is_member": true,
    "member_role": 20,
    "is_deployed": true,
    "module_view": true,
    "cycle_view": true,
    "issue_views_view": true,
    "page_view": true,
    "intake_view": false,
    "archive_in": 30,
    "close_in": 7,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-03-09T14:30:00Z"
  }
]

Create Project

POST

Create a new project in a workspace.

Path Parameters

slug

string

required

Workspace slug identifier

Request Body

name

string

required

Project name (cannot contain special characters)

identifier

string

required

Unique project identifier (uppercase, no special characters, e.g., “MOBILE”)

description

string

Project description (supports HTML)

project_lead

uuid

User ID of the project lead (must be workspace member)

default_assignee

uuid

User ID for default assignee (must be workspace member)

icon_prop

string

Icon property for the project

emoji

string

Emoji representation

cover_image

string

Cover image URL

module_view

boolean

default:true

Enable modules feature

cycle_view

boolean

default:true

Enable cycles feature

issue_views_view

boolean

default:true

Enable issue views feature

page_view

boolean

default:true

Enable pages feature

intake_view

boolean

default:false

Enable intake feature

guest_view_all_features

boolean

default:false

Allow guests to view all features

archive_in

integer

default:30

Days before auto-archiving closed issues

close_in

integer

default:7

Days before auto-closing stale issues

timezone

string

Project timezone (e.g., “America/New_York”)

is_issue_type_enabled

boolean

default:false

Enable issue types feature

is_time_tracking_enabled

boolean

default:false

Enable time tracking feature

external_source

string

External integration source

external_id

string

External system identifier

Example Request

curl -X POST "https://api.plane.so/api/v1/workspaces/acme/projects/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App",
    "identifier": "MOBILE",
    "description": "iOS and Android mobile application",
    "project_lead": "350e8400-e29b-41d4-a716-446655440000",
    "module_view": true,
    "cycle_view": true,
    "timezone": "America/New_York"
  }'

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Mobile App",
  "identifier": "MOBILE",
  "description": "iOS and Android mobile application",
  "logo_props": {
    "in_use": "icon",
    "icon": {
      "name": "rocket",
      "color": "#5e6ad2"
    }
  },
  "workspace_id": "750e8400-e29b-41d4-a716-446655440000",
  "project_lead": "350e8400-e29b-41d4-a716-446655440000",
  "module_view": true,
  "cycle_view": true,
  "timezone": "America/New_York",
  "created_at": "2024-03-09T15:00:00Z",
  "updated_at": "2024-03-09T15:00:00Z"
}

Get Project

GET

Retrieve a specific project by ID.

Path Parameters

slug

string

required

Workspace slug identifier

uuid

required

Project UUID

Example Request

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

Update Project

PATCH

Update a project’s properties.

Request Body

All fields from the create endpoint plus:

default_state

uuid

Default state ID for new issues (must be a state in the project)

estimate

uuid

Estimate ID for story points (must belong to the project)

Example Request

curl -X PATCH "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile Application",
    "archive_in": 60
  }'

Delete Project

DELETE

Delete a project permanently.

Example Request

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

Deleting a project will permanently remove all associated work items, cycles, modules, and data. This action cannot be undone.

Project Archive

Archive Project

POST

Archive a project to hide it from active project lists.

Example Request

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

Unarchive Project

DELETE

Restore an archived project.

Example Request

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

Project Summary

Get Project Summary

GET

Retrieve aggregated statistics and insights for a project.

Example Request

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

Project Response Fields

uuid

Unique project identifier

name

string

Project name

identifier

string

Short project identifier (e.g., “MOBILE”)

description

string

Project description

logo_props

object

Project logo/icon configuration

Show properties

in_use

string

Active logo type: icon, emoji, image

icon

object

Icon configuration with name and color

workspace_id

uuid

Parent workspace ID

total_members

integer

Number of project members

total_cycles

integer

Number of cycles in the project

total_modules

integer

Number of modules in the project

is_member

boolean

Whether the current user is a project member

member_role

integer

Current user’s role level (5=guest, 10=viewer, 15=member, 20=admin)

is_deployed

boolean

Whether the project is deployed

created_at

datetime

Project creation timestamp

updated_at

datetime

Last update timestamp

Validation Rules

Name: Cannot contain special characters matching FORBIDDEN_IDENTIFIER_CHARS_PATTERN
Identifier: Must be uppercase, unique within workspace, no special characters
Project Lead: Must be a member of the workspace
Default Assignee: Must be a member of the workspace
Default State: Must be a state that belongs to the project
Estimate: Must be an estimate configuration that belongs to the project

Error Responses

Invalid Identifier

{
  "error": "Project identifier cannot contain special characters."
}

Identifier Already Taken

{
  "detail": "Project Identifier is taken"
}

Invalid Project Lead

{
  "error": "Project lead should be a user in the workspace"
}

Invalid Default State

{
  "error": "Default state should be a state in the project"
}

Default Project Configuration

When creating a project without a logo_props field, Plane automatically generates a random icon and color: Available Colors:

#95999f, #6d7b8a, #5e6ad2, #02b5ed, #02b55c, #f2be02, #e57a00, #f38e82

Available Icons:

home, apps, settings, star, favorite, done, check_circle, add_task, create_new_folder, dataset, terminal, key, rocket, public, quiz, mood, gavel, eco, diamond, forest, bolt, sync, cached, library_add, view_timeline, view_kanban, empty_dashboard, cycle

Overview

Endpoints

Projects

Projects API

Endpoints

List Projects

Path Parameters

Query Parameters

Example Request

Response

Create Project

Path Parameters

Request Body

Example Request

Response

Get Project

Path Parameters

Example Request

Update Project

Request Body

Example Request

Delete Project

Example Request

Project Archive

Archive Project

Example Request

Unarchive Project

Example Request

Project Summary

Get Project Summary

Example Request

Project Response Fields

Validation Rules

Error Responses

Invalid Identifier

Identifier Already Taken

Invalid Project Lead

Invalid Default State

Default Project Configuration

Build docs developers (and LLMs) love

Overview

Endpoints

​Projects API

​Endpoints

​List Projects

​Path Parameters

​Query Parameters

​Example Request

​Response

​Create Project

​Path Parameters

​Request Body

​Example Request

​Response

​Get Project

​Path Parameters

​Example Request

​Update Project

​Request Body

​Example Request

​Delete Project

​Example Request

​Project Archive

​Archive Project

​Example Request

​Unarchive Project

​Example Request

​Project Summary

​Get Project Summary

​Example Request

​Project Response Fields

​Validation Rules

​Error Responses

​Invalid Identifier

​Identifier Already Taken

​Invalid Project Lead

​Invalid Default State

​Default Project Configuration

Build docs developers (and LLMs) love

Projects API

Endpoints

List Projects

Path Parameters

Query Parameters

Example Request

Response

Create Project

Path Parameters

Request Body

Example Request

Response

Get Project

Path Parameters

Example Request

Update Project

Request Body

Example Request

Delete Project

Example Request

Project Archive

Archive Project

Example Request

Unarchive Project

Example Request

Project Summary

Get Project Summary

Example Request

Project Response Fields

Validation Rules

Error Responses

Invalid Identifier

Identifier Already Taken

Invalid Project Lead

Invalid Default State

Default Project Configuration