Lifecycle Stages

Manage project lifecycle stages that track project progress from planning through completion.

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

Returns a paginated list of lifecycle stages in the organization.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Records per page (max 200)
search	string	—	Search by name
sortBy	string	name	Sort field: 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&limit=50" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx5a6b7c8d9e0f1",
      "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": "clx1e2n3g4r5o0t6",
      "name": "Ready for Development",
      "category": "TODO",
      "color": "#6366F1",
      "sortOrder": 1,
      "isSystemDefault": false,
      "isArchived": false,
      "createdAt": "2024-01-05T08:00:00Z",
      "updatedAt": "2025-09-01T10:00:00Z"
    },
    {
      "id": "clx6t7u8v9w0x1y2",
      "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": 50,
    "total": 5,
    "hasNextPage": false
  }
}

---

Get Lifecycle Stage

GET /org/:orgId/lifecycle-stages/:id

Returns a single lifecycle stage by ID.

Example Request

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

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "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"
  }
}

---

Create Lifecycle Stage

POST /org/:orgId/lifecycle-stages

Creates a new lifecycle stage.

Request Body

{
  "name": "In Development",
  "category": "IN_PROGRESS",
  "color": "#3B82F6",
  "sortOrder": 2
}

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
  }'

Example Response

{
  "data": {
    "id": "clx3d4e5f6g7h8i9",
    "name": "In Development",
    "category": "IN_PROGRESS",
    "color": "#3B82F6",
    "sortOrder": 2,
    "isSystemDefault": false,
    "isArchived": false,
    "createdAt": "2026-03-11T09:40:00Z",
    "updatedAt": "2026-03-11T09:40:00Z"
  }
}

Status: 201 Created

---

Update Lifecycle Stage

PATCH /org/:orgId/lifecycle-stages/:id

Updates one or more fields on an existing lifecycle stage. Only include the fields you want to change.

Example Request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/lifecycle-stages/clx6t7u8v9w0x1y2" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Development",
    "color": "#2563EB"
  }'

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "name": "Active Development",
    "category": "IN_PROGRESS",
    "color": "#2563EB",
    "sortOrder": 2,
    "isSystemDefault": false,
    "isArchived": false,
    "createdAt": "2024-01-05T08:00:00Z",
    "updatedAt": "2026-03-11T09:45:00Z"
  }
}

---

Delete Lifecycle Stage

DELETE /org/:orgId/lifecycle-stages/:id

Deletes a lifecycle stage. System default stages and stages that are actively assigned to projects cannot be deleted until those references are removed.

Example Request

curl -X DELETE "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/lifecycle-stages/clx6t7u8v9w0x1y2" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "deleted": true
  }
}

Status: 200 OK

---

Category Values

The category field classifies each lifecycle stage into one of five progression phases:

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

---

Field Reference

Field	Type	Required	Description
id	string	—	Unique identifier (read-only)
name	string	Yes	Lifecycle stage name
category	enum	No	Stage category (default: "PLANNING")
color	string	No	Hex color for UI display (default: "#6B7280")
sortOrder	integer	No	Display sort order (default: 0)
isSystemDefault	boolean	No	Whether this is a system default stage (default: false)
isArchived	boolean	No	Whether the stage is archived (default: false)
createdAt	datetime	—	Record creation timestamp (read-only)
updatedAt	datetime	—	Last modification timestamp (read-only)