Modules API

Modules are feature-based groupings of work items in Plane projects. This API allows you to create, manage, and track modules and their associated work items.

Endpoints

List Modules

GET

Retrieve all modules in a project.

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/modules/" \
  -H "X-Api-Key: your_api_key"

Response

[
  {
    "id": "470e8400-e29b-41d4-a716-446655440000",
    "name": "User Authentication",
    "description": "OAuth 2.0 and SSO implementation",
    "start_date": "2024-03-01",
    "target_date": "2024-03-31",
    "status": "in_progress",
    "lead": "350e8400-e29b-41d4-a716-446655440000",
    "members": [
      "350e8400-e29b-41d4-a716-446655440000",
      "360e8400-e29b-41d4-a716-446655440000"
    ],
    "workspace_id": "750e8400-e29b-41d4-a716-446655440000",
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "total_issues": 18,
    "completed_issues": 12,
    "started_issues": 4,
    "unstarted_issues": 2,
    "backlog_issues": 0,
    "cancelled_issues": 0,
    "created_at": "2024-02-15T10:00:00Z",
    "updated_at": "2024-03-09T14:30:00Z"
  }
]

Create Module

POST

Create a new module in a project.

Modules must be enabled for the project (module_view: true) before creating modules.

Path Parameters

string

required

Workspace slug identifier

uuid

required

Project UUID

Request Body

string

required

Module name (must be unique within the project)

string

Module description

date

Module start date (YYYY-MM-DD)

date

Module target date (YYYY-MM-DD, cannot be before start_date)

string

Module status: backlog, planned, in_progress, paused, completed, cancelled

uuid

User ID of module lead (must be a project member)

array

Array of user IDs to assign as module members (must be project members)

string

External integration source

string

External system identifier

Example Request

curl -X POST "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/modules/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Integration",
    "description": "Stripe payment gateway integration",
    "start_date": "2024-04-01",
    "target_date": "2024-04-30",
    "status": "planned",
    "lead": "350e8400-e29b-41d4-a716-446655440000",
    "members": [
      "350e8400-e29b-41d4-a716-446655440000",
      "360e8400-e29b-41d4-a716-446655440000"
    ]
  }'

Response

{
  "id": "480e8400-e29b-41d4-a716-446655440000",
  "name": "Payment Integration",
  "description": "Stripe payment gateway integration",
  "start_date": "2024-04-01",
  "target_date": "2024-04-30",
  "status": "planned",
  "lead": "350e8400-e29b-41d4-a716-446655440000",
  "members": [
    "350e8400-e29b-41d4-a716-446655440000",
    "360e8400-e29b-41d4-a716-446655440000"
  ],
  "workspace_id": "750e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "total_issues": 0,
  "completed_issues": 0,
  "created_at": "2024-03-09T15:30:00Z",
  "updated_at": "2024-03-09T15:30:00Z"
}

Get Module

GET

Retrieve a specific module by ID.

Path Parameters

string

required

Workspace slug identifier

uuid

required

Project UUID

uuid

required

Module UUID

Example Request

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

Update Module

PATCH

Update a module’s properties.

Example Request

curl -X PATCH "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/modules/470e8400-e29b-41d4-a716-446655440000/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "target_date": "2024-04-15"
  }'

Delete Module

DELETE

Delete a module permanently.

Example Request

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

Module Issues

List Module Issues

GET

Retrieve all work items assigned to a module.

Example Request

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

Add Issues to Module

POST

Assign work items to a module in bulk.

Request Body

array

required

Array of issue UUIDs to add to the module

Example Request

curl -X POST "https://api.plane.so/api/v1/workspaces/acme/projects/550e8400-e29b-41d4-a716-446655440000/modules/470e8400-e29b-41d4-a716-446655440000/module-issues/" \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "issues": [
      "650e8400-e29b-41d4-a716-446655440000",
      "660e8400-e29b-41d4-a716-446655440000"
    ]
  }'

Remove Issue from Module

DELETE

Remove a work item from a module.

Example Request

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

Module Archive

Archive Module

POST

Archive a module to remove it from active module lists.

Example Request

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

List Archived Modules

GET

Retrieve all archived modules in a project.

Example Request

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

Unarchive Module

DELETE

Restore an archived module.

Example Request

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

Module Response Fields

uuid

Unique module identifier

string

Module name

string

Module description

date

Module start date

date

Module target date

string

Module status: backlog, planned, in_progress, paused, completed, cancelled

uuid

User ID of module lead

array

Array of user IDs who are module members

integer

Total number of work items in the module

integer

Number of completed work items

integer

Number of started work items

integer

Number of unstarted work items

integer

Number of backlog work items

integer

Number of cancelled work items

datetime

Module creation timestamp

datetime

Last update timestamp

Validation Rules

Project Modules Enabled: Modules must be enabled for the project (module_view: true)
Unique Name: Module name must be unique within the project
Date Range: start_date cannot exceed target_date
Members: All members must be active project members
Lead: Module lead must be a project member

Error Responses

Modules Not Enabled

{
  "error": "Modules are not enabled for this project"
}

Duplicate Module Name

{
  "id": "470e8400-e29b-41d4-a716-446655440000",
  "code": "MODULE_NAME_ALREADY_EXISTS",
  "error": "Module with this name already exists",
  "message": "Module with this name already exists"
}

Invalid Date Range

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

Project Not Found

{
  "error": "Project not found"
}

​Modules API

​Endpoints

​List Modules

​Path Parameters

​Example Request

​Response

​Create Module

​Path Parameters

​Request Body

​Example Request

​Response

​Get Module

​Path Parameters

​Example Request

​Update Module

​Example Request

​Delete Module

​Example Request

​Module Issues

​List Module Issues

​Example Request

​Add Issues to Module

​Request Body

​Example Request

​Remove Issue from Module

​Example Request

​Module Archive

​Archive Module

​Example Request

​List Archived Modules

​Example Request

​Unarchive Module

​Example Request

​Module Response Fields

​Validation Rules

​Error Responses

​Modules Not Enabled

​Duplicate Module Name

​Invalid Date Range

​Project Not Found

Modules API

Endpoints

List Modules

Path Parameters

Example Request

Response

Create Module

Path Parameters

Request Body

Example Request

Response

Get Module

Path Parameters

Example Request

Update Module

Example Request

Delete Module

Example Request

Module Issues

List Module Issues

Example Request

Add Issues to Module

Request Body

Example Request

Remove Issue from Module

Example Request

Module Archive

Archive Module

Example Request

List Archived Modules

Example Request

Unarchive Module

Example Request

Module Response Fields

Validation Rules

Error Responses

Modules Not Enabled

Duplicate Module Name

Invalid Date Range

Project Not Found