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

string

required

Workspace slug identifier

Query Parameters

string

Search term to filter projects

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

string

required

Workspace slug identifier

Request Body

string

required

Project name (cannot contain special characters)

string

required

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

string

Project description (supports HTML)

uuid

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

uuid

User ID for default assignee (must be workspace member)

string

Icon property for the project

string

Emoji representation

string

Cover image URL

boolean

default:true

Enable modules feature

boolean

default:true

Enable cycles feature

boolean

default:true

Enable issue views feature

boolean

default:true

Enable pages feature

boolean

default:false

Enable intake feature

boolean

default:false

Allow guests to view all features

integer

default:30

Days before auto-archiving closed issues

integer

default:7

Days before auto-closing stale issues

string

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

boolean

default:false

Enable issue types feature

boolean

default:false

Enable time tracking feature

string

External integration source

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

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:

uuid

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

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

string

Project name

string

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

string

Project description

object

Project logo/icon configuration

Show properties

string

Active logo type: icon, emoji, image

object

Icon configuration with name and color

uuid

Parent workspace ID

integer

Number of project members

integer

Number of cycles in the project

integer

Number of modules in the project

boolean

Whether the current user is a project member

integer

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

boolean

Whether the project is deployed

datetime

Project creation timestamp

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

​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

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