Create Epics, Issues, Tasks, Bugs, and Sub-tasks

Work items are the individual units of work inside a PPM project. This guide shows you how to create each type.

Work item types

Type	Description	Can be a child of
EPIC	A strategic initiative that spans multiple deliverables	EPIC
ISSUE	A concrete deliverable piece of work	EPIC
TASK	A granular work unit	EPIC, ISSUE
BUG	A defect to be fixed	EPIC, ISSUE
SUB_TASK	A leaf-level breakdown of a task, bug, or issue	ISSUE, TASK, BUG

note

Sub-tasks cannot have children. See Organise work items into a hierarchy for full hierarchy rules.

Auto-generated work item key

Every work item receives a unique work_item_key in the format WI-NNNNNNN (e.g. WI-0000001). You do not need to supply this — the system generates it on insert.

Create an epic

POST /rest/v1/t_ppm_work_items

{
  "project_id": "a1b2c3d4-...",
  "work_item_type": "EPIC",
  "work_item_name": "Onboarding Flow Redesign",
  "work_item_description": "Redesign the entire onboarding experience.",
  "work_item_priority": "HIGH"
}

Response (201 Created)

{
  "id": "e5f6a7b8-...",
  "work_item_key": "WI-0000001",
  "work_item_type": "EPIC",
  "work_item_name": "Onboarding Flow Redesign",
  "work_item_status": "BACKLOG",
  "work_item_priority": "HIGH",
  "project_id": "a1b2c3d4-..."
}

Create an issue

POST /rest/v1/t_ppm_work_items

{
  "project_id": "a1b2c3d4-...",
  "work_item_type": "ISSUE",
  "work_item_name": "Build new welcome screen",
  "work_item_priority": "MEDIUM",
  "parent_work_item_id": "e5f6a7b8-..."
}

Create a task

POST /rest/v1/t_ppm_work_items

{
  "project_id": "a1b2c3d4-...",
  "work_item_type": "TASK",
  "work_item_name": "Implement welcome screen API endpoint",
  "parent_work_item_id": "e5f6a7b8-...",
  "estimated_work_minutes": 480
}

Create a bug

POST /rest/v1/t_ppm_work_items

{
  "project_id": "a1b2c3d4-...",
  "work_item_type": "BUG",
  "work_item_name": "Welcome email not sent on signup",
  "work_item_priority": "CRITICAL",
  "parent_work_item_id": "e5f6a7b8-..."
}

Create a sub-task

POST /rest/v1/t_ppm_work_items

{
  "project_id": "a1b2c3d4-...",
  "work_item_type": "SUB_TASK",
  "work_item_name": "Write unit tests for welcome endpoint",
  "parent_work_item_id": "<task-or-issue-id>"
}

Work item statuses

Every work item starts in BACKLOG by default. The available statuses are:

Status	Category	Description
BACKLOG	Unstarted	Not yet planned
SELECTED	Unstarted	In backlog, ready to pick up
TODO	Unstarted	Planned for the current milestone
IN_PROGRESS	Started	Work is underway
IN_REVIEW	Started	Code review or MR open
TESTING	Started	QA or verification
BLOCKED	Started	Waiting on a dependency
DONE	Completed	Finished
CANCELLED	Cancelled	Will not be done

The work_item_status_category field is auto-computed from the status.

Update a work item's status

PATCH /rest/v1/t_ppm_work_items?id=eq.<work-item-id>

{
  "work_item_status": "IN_PROGRESS",
  "actual_start_date": "2026-05-03T09:00:00Z"
}

Work item priorities

Priority	Description
CRITICAL	Highest priority
HIGH	High priority
MEDIUM	Normal priority (default)
LOW	Low priority

Available fields

Field	Type	Required	Default	Description
project_id	uuid	Yes	—	The parent project
work_item_type	varchar(32)	Yes	—	EPIC, ISSUE, TASK, BUG, or SUB_TASK
work_item_name	varchar(256)	Yes	—	Display name
work_item_description	text	No	—	Longer description
work_item_status	varchar(32)	No	BACKLOG	See status table above
work_item_priority	varchar(32)	No	MEDIUM	See priority table above
health_status	varchar(32)	No	—	ON_TRACK, NEEDS_ATTENTION, or AT_RISK
parent_work_item_id	uuid	No	—	Parent work item (hierarchy rules apply)
milestone_id	uuid	No	—	Milestone this work item belongs to
due_date	timestamptz	No	—	Target completion date
weight	integer	No	—	Relative sizing / story points
estimated_work_minutes	integer	No	—	Estimated effort in minutes
percent_complete	smallint	No	0	0–100 progress indicator
confidential	boolean	No	false	Restrict visibility
display_order	integer	No	0	Sort order within a list
external_ref	varchar(512)	No	—	External reference (e.g. GitLab issue number)
external_url	varchar(1024)	No	—	URL to external issue
metadata	jsonb	No	—	Arbitrary key-value data