Skip to main content

​
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

​
slug
string
required
Workspace slug identifier
​
project_id
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

​
slug
string
required
Workspace slug identifier
​
project_id
uuid
required
Project UUID

​
Request Body

​
name
string
required
Module name (must be unique within the project)
​
description
string
Module description
​
start_date
date
Module start date (YYYY-MM-DD)
​
target_date
date
Module target date (YYYY-MM-DD, cannot be before start_date)
​
status
string
Module status: backlog, planned, in_progress, paused, completed, cancelled
​
lead
uuid
User ID of module lead (must be a project member)
​
members
array
Array of user IDs to assign as module members (must be project members)
​
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/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

​
slug
string
required
Workspace slug identifier
​
project_id
uuid
required
Project UUID
​
pk
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

​
issues
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

​
id
uuid
Unique module identifier
​
name
string
Module name
​
description
string
Module description
​
start_date
date
Module start date
​
target_date
date
Module target date
​
status
string
Module status: backlog, planned, in_progress, paused, completed, cancelled
​
lead
uuid
User ID of module lead
​
members
array
Array of user IDs who are module members
​
total_issues
integer
Total number of work items in the module
​
completed_issues
integer
Number of completed work items
​
started_issues
integer
Number of started work items
​
unstarted_issues
integer
Number of unstarted work items
​
backlog_issues
integer
Number of backlog work items
​
cancelled_issues
integer
Number of cancelled work items
​
created_at
datetime
Module creation timestamp
​
updated_at
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"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us