Add work items to epic

POST/api/v1/workspaces/{slug}/projects/{project_id}/epics/{epic_id}/issues/

Add multiple work items as sub-issues under an epic. Validates type hierarchy before assignment.

Path Parameters

epic_id:requiredstring

Epic ID

project_id:requiredstring

Project ID

slug:requiredstring

Workspace slug

Body Parameters

work_item_ids:requiredarray

List of work item IDs to add to the epic

Scopes

projects.epics:write

Add work items to epic

curl -X POST \
  "https://api.plane.so/api/v1/workspaces/my-workspace/projects/550e8400-e29b-41d4-a716-446655440000/epics/550e8400-e29b-41d4-a716-446655440001/issues/" \
  -H "X-API-Key: $PLANE_API_KEY" \
  # Or use -H "Authorization: Bearer $PLANE_OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "work_item_ids": [
    "550e8400-e29b-41d4-a716-446655440010",
    "550e8400-e29b-41d4-a716-446655440011"
  ]
}'

import requests

response = requests.post(
    "https://api.plane.so/api/v1/workspaces/my-workspace/projects/550e8400-e29b-41d4-a716-446655440000/epics/550e8400-e29b-41d4-a716-446655440001/issues/",
    headers={"X-API-Key": "your-api-key"},
    json={
      "work_item_ids": [
        "550e8400-e29b-41d4-a716-446655440010",
        "550e8400-e29b-41d4-a716-446655440011"
      ]
    }
)
print(response.json())

const response = await fetch(
  "https://api.plane.so/api/v1/workspaces/my-workspace/projects/550e8400-e29b-41d4-a716-446655440000/epics/550e8400-e29b-41d4-a716-446655440001/issues/",
  {
    method: "POST",
    headers: {
      "X-API-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      work_item_ids: ["550e8400-e29b-41d4-a716-446655440010", "550e8400-e29b-41d4-a716-446655440011"],
    }),
  }
);
const data = await response.json();

Response200

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "name": "Implement login screen",
    "description_html": "<p>Build the login screen UI</p>",
    "description_stripped": "Build the login screen UI",
    "description_binary": null,
    "state": "550e8400-e29b-41d4-a716-446655440002",
    "priority": "high",
    "assignees": [],
    "labels": [],
    "type": null,
    "type_id": null,
    "estimate_point": null,
    "point": null,
    "start_date": null,
    "target_date": null,
    "parent": "550e8400-e29b-41d4-a716-446655440001",
    "sequence_id": 12,
    "sort_order": 65535.0,
    "is_draft": false,
    "completed_at": null,
    "archived_at": null,
    "last_activity_at": "2025-03-15T10:00:00Z",
    "project": "550e8400-e29b-41d4-a716-446655440000",
    "workspace": "550e8400-e29b-41d4-a716-446655440003",
    "external_id": null,
    "external_source": null,
    "deleted_at": null,
    "created_at": "2025-03-10T09:00:00Z",
    "updated_at": "2025-03-15T10:00:00Z",
    "created_by": "550e8400-e29b-41d4-a716-446655440005",
    "updated_by": null
  }
]