Projects

Manage projects with timelines, cost tracking, and resource assignments. Projects represent work initiatives that teams and individuals are allocated to, with start/end dates and financial estimates.

Endpoints

Method	Path	Description
GET	/org/:orgId/projects	List projects
GET	/org/:orgId/projects/:id	Get project
POST	/org/:orgId/projects	Create project
PATCH	/org/:orgId/projects/:id	Update project
DELETE	/org/:orgId/projects/:id	Delete project

---

List Projects

GET /org/:orgId/projects

Returns a paginated list of projects 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 or description
sortBy	string	name	Sort field
sortDir	string	asc	asc or desc
scenarioId	string	—	Scenario ID for what-if queries

Example Request

curl -X GET "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/projects?sortBy=startDate&sortDir=desc&limit=10" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx7p8r9q0s1t2u3",
      "name": "Billing V2",
      "description": "Rebuild the billing system with usage-based pricing support.",
      "startDate": "2026-01-15",
      "endDate": "2026-09-30",
      "status": "active",
      "estimatedCost": "450000.00",
      "icon": "credit-card",
      "iconColor": "#6B7280",
      "ownerUserId": "clx9u1s2e3r4",
      "lifecycleStageId": "clx2l3c4s5t6",
      "metadata": {},
      "createdAt": "2025-11-01T09:00:00Z",
      "updatedAt": "2026-02-15T16:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 34,
    "hasNextPage": true
  }
}

---

Get Project

GET /org/:orgId/projects/:id

Returns a single project by ID.

Example Request

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

Example Response

{
  "data": {
    "id": "clx7p8r9q0s1t2u3",
    "name": "Billing V2",
    "description": "Rebuild the billing system with usage-based pricing support.",
    "startDate": "2026-01-15",
    "endDate": "2026-09-30",
    "status": "active",
    "estimatedCost": "450000.00",
    "icon": "credit-card",
    "iconColor": "#6B7280",
    "ownerUserId": "clx9u1s2e3r4",
    "lifecycleStageId": "clx2l3c4s5t6",
    "metadata": {},
    "createdAt": "2025-11-01T09:00:00Z",
    "updatedAt": "2026-02-15T16:30:00Z"
  }
}

---

Create Project

POST /org/:orgId/projects

Creates a new project.

Request Body

{
  "name": "Mobile App Redesign",
  "description": "Complete redesign of the iOS and Android mobile applications.",
  "startDate": "2026-04-01",
  "endDate": "2026-12-31",
  "status": "planning",
  "estimatedCost": "320000.00",
  "ownerUserId": "clx9u1s2e3r4",
  "lifecycleStageId": "clx2l3c4s5t6"
}

Example Request

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/projects" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App Redesign",
    "description": "Complete redesign of the iOS and Android mobile applications.",
    "startDate": "2026-04-01",
    "endDate": "2026-12-31",
    "status": "planning"
  }'

Example Response

{
  "data": {
    "id": "clx4m5n6o7p8q9r0",
    "name": "Mobile App Redesign",
    "description": "Complete redesign of the iOS and Android mobile applications.",
    "startDate": "2026-04-01",
    "endDate": "2026-12-31",
    "status": "planning",
    "estimatedCost": null,
    "icon": null,
    "iconColor": "#6B7280",
    "ownerUserId": null,
    "lifecycleStageId": null,
    "metadata": {},
    "createdAt": "2026-03-11T09:50:00Z",
    "updatedAt": "2026-03-11T09:50:00Z"
  }
}

Status: 201 Created

---

Update Project

PATCH /org/:orgId/projects/:id

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

Example Request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/projects/clx7p8r9q0s1t2u3" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "endDate": "2026-08-15"
  }'

Example Response

{
  "data": {
    "id": "clx7p8r9q0s1t2u3",
    "name": "Billing V2",
    "description": "Rebuild the billing system with usage-based pricing support.",
    "startDate": "2026-01-15",
    "endDate": "2026-08-15",
    "status": "completed",
    "estimatedCost": "450000.00",
    "icon": "credit-card",
    "iconColor": "#6B7280",
    "ownerUserId": "clx9u1s2e3r4",
    "lifecycleStageId": "clx2l3c4s5t6",
    "metadata": {},
    "createdAt": "2025-11-01T09:00:00Z",
    "updatedAt": "2026-03-11T09:55:00Z"
  }
}

---

Delete Project

DELETE /org/:orgId/projects/:id

Deletes a project. Projects with active assignments cannot be deleted until those assignments are removed.

Example Request

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

Status: 204 No Content

---

Field Reference

Field	Type	Required	Description
id	string	—	Unique identifier (read-only)
name	string	Yes	Project name
description	string	No	Project description
startDate	date	No	Project start date (ISO 8601: YYYY-MM-DD)
endDate	date	No	Project end date (null = no end date)
status	string	No	Status: "planning", "active", "completed", "on_hold", "cancelled"
estimatedCost	decimal	No	Estimated total cost of the project
icon	string	No	Icon identifier for the project
iconColor	string	No	Hex color for the icon (default: "#6B7280")
ownerUserId	string	No	ID of the user who owns this project
lifecycleStageId	string	No	ID of the project lifecycle stage
metadata	object	No	Arbitrary JSON metadata (default: {})
createdAt	datetime	—	Record creation timestamp (read-only)
updatedAt	datetime	—	Last modification timestamp (read-only)