Create and Archive a Project

This guide walks you through creating a PPM project and moving it through its lifecycle statuses.

Project status lifecycle

Every project follows this status path:

PROPOSED → ACTIVE → ON_HOLD → COMPLETED
                            → CANCELLED

Status	Meaning
PROPOSED	Default. The project has been proposed but work has not started.
ACTIVE	The project is in progress.
ON_HOLD	The project is paused.
COMPLETED	The project has finished successfully.
CANCELLED	The project was cancelled and will not be completed.

Create a project

Send a POST request to the projects endpoint. Only project_name is required — the system auto-generates a project_key if you omit it.

POST /rest/v1/t_ppm_projects

{
  "project_name": "Customer Onboarding Revamp",
  "project_description": "Redesign the onboarding flow for new customers.",
  "project_status": "PROPOSED",
  "project_priority": "HIGH",
  "planned_start_date": "2026-05-01T00:00:00Z",
  "planned_end_date": "2026-08-31T23:59:59Z"
}

The response includes the auto-generated fields:

Response (201 Created)

{
  "id": "a1b2c3d4-...",
  "project_key": "PRJ-0000001",
  "project_name": "Customer Onboarding Revamp",
  "project_status": "PROPOSED",
  "project_priority": "HIGH",
  "planned_start_date": "2026-05-01T00:00:00+00:00",
  "planned_end_date": "2026-08-31T23:59:59+00:00",
  "created_date": "2026-04-13T10:00:00+00:00"
}

Available fields

Field	Type	Required	Default	Description
project_name	varchar(256)	Yes	—	Display name
project_description	text	No	—	Longer description
project_status	varchar(32)	No	PROPOSED	One of the lifecycle statuses above
project_priority	varchar(32)	No	MEDIUM	CRITICAL, HIGH, MEDIUM, or LOW
project_key	varchar(64)	No	Auto-generated	Unique human-readable key
project_manager_id	uuid	No	—	User ID of the project manager
planned_start_date	timestamptz	No	—	Expected start
planned_end_date	timestamptz	No	—	Expected end
actual_start_date	timestamptz	No	—	When work actually started
actual_end_date	timestamptz	No	—	When work actually finished
confidential	boolean	No	false	Restrict visibility to owner and authorised users
metadata	jsonb	No	—	Arbitrary key-value data

Activate a project

When work begins, update the status to ACTIVE and record the actual start date:

PATCH /rest/v1/t_ppm_projects?id=eq.a1b2c3d4-...

{
  "project_status": "ACTIVE",
  "actual_start_date": "2026-05-02T09:00:00Z"
}

Put a project on hold

PATCH /rest/v1/t_ppm_projects?id=eq.a1b2c3d4-...

{
  "project_status": "ON_HOLD"
}

Complete or cancel a project

Mark a project as finished:

PATCH /rest/v1/t_ppm_projects?id=eq.a1b2c3d4-...

{
  "project_status": "COMPLETED",
  "actual_end_date": "2026-08-15T17:00:00Z"
}

Or cancel it:

PATCH /rest/v1/t_ppm_projects?id=eq.a1b2c3d4-...

{
  "project_status": "CANCELLED",
  "actual_end_date": "2026-06-01T12:00:00Z"
}

Archive a project

To soft-delete (archive) a project, set active to false:

PATCH /rest/v1/t_ppm_projects?id=eq.a1b2c3d4-...

{
  "active": false
}

Archived projects are excluded from default queries but remain in the database.

note

Setting a project's status to COMPLETED or CANCELLED does not automatically archive it. Archive the project separately when you no longer need it in active views.