Lifecycle Stages

Manage project lifecycle stages that track project progress from planning through completion. Each stage belongs to a category that defines the phase of work.

Lifecycle Stage Object

Field	Type	Description
id	string	Unique identifier (CUID format). System-generated. Read-only.
name	string	Stage name (e.g. "Discovery", "In Development", "Shipped").
category	string	Stage category. One of: "PLANNING", "TODO", "IN_PROGRESS", "COMPLETED", "DISREGARDED".
color	string	Hex colour for UI display (e.g. "#3B82F6").
sortOrder	integer	Display ordering weight. Lower values appear first.
isSystemDefault	boolean	Whether this is a system-provided default stage. System defaults cannot be deleted.
isArchived	boolean	Whether the stage is archived. Archived stages are hidden from selection lists.
createdAt	datetime (ISO 8601)	When the record was created. Read-only.
updatedAt	datetime (ISO 8601)	When the record was last modified. Read-only.

Category Values

Value	Description
PLANNING	Early-stage ideation and scoping.
TODO	Approved and ready to begin.
IN_PROGRESS	Actively being worked on.
COMPLETED	Successfully delivered.
DISREGARDED	Cancelled or deprioritized.

---

Endpoints

Method	Path	Description
GET	/org/:orgId/lifecycle-stages	List lifecycle stages
GET	/org/:orgId/lifecycle-stages/:id	Get lifecycle stage
POST	/org/:orgId/lifecycle-stages	Create lifecycle stage
PATCH	/org/:orgId/lifecycle-stages/:id	Update lifecycle stage
DELETE	/org/:orgId/lifecycle-stages/:id	Delete lifecycle stage

---

List Lifecycle Stages

GET /org/:orgId/lifecycle-stages

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-based).
limit	integer	20	Records per page. Min 1, max 100.
search	string	--	Free-text search by name.
sortBy	string	name	Field to sort by: name, category, sortOrder, createdAt.
sortDir	string	asc	asc or desc.

Example Request

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/lifecycle-stages?sortBy=sortOrder" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx5a6b7c8d9e0f1g2h3",
      "name": "Discovery",
      "category": "PLANNING",
      "color": "#F59E0B",
      "sortOrder": 0,
      "isSystemDefault": true,
      "isArchived": false,
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2025-11-20T14:00:00Z"
    },
    {
      "id": "clx6t7u8v9w0x1y2z3a4",
      "name": "In Development",
      "category": "IN_PROGRESS",
      "color": "#3B82F6",
      "sortOrder": 2,
      "isSystemDefault": false,
      "isArchived": false,
      "createdAt": "2024-01-05T08:00:00Z",
      "updatedAt": "2025-09-01T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "hasNextPage": false
  }
}

---

Create Lifecycle Stage

POST /org/:orgId/lifecycle-stages

Create Request Body

Field	Type	Required	Description
name	string	Yes	Stage name.
category	string	No	One of "PLANNING", "TODO", "IN_PROGRESS", "COMPLETED", "DISREGARDED".
color	string	No	Hex colour for UI display. Default: "#6B7280".
sortOrder	integer	No	Display ordering. Default: 0.
isSystemDefault	boolean	No	Default: false.
isArchived	boolean	No	Default: false.

Update Request Body

All fields from Create are accepted, all optional.

Example Request

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/lifecycle-stages" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "In Development",
    "category": "IN_PROGRESS",
    "color": "#3B82F6",
    "sortOrder": 2
  }'

Status: 201 Created

---

Error Responses

Validation Error (400)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [{ "field": "name", "message": "name is required" }],
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

Not Found (404)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Lifecycle stage not found.",
    "errorId": "err_clx9a8b7c6d5e4f3"
  }
}

---

Related Endpoints

• Projects -- Projects reference lifecycle stages via lifecycleStageId.