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.

Project Object

Field	Type	Description
id	string	Unique identifier (CUID format). System-generated. Read-only.
externalId	string | null	Your external identifier for this project. Unique within your organization. Use for lookups via path parameters.
name	string	Project name (e.g. "Billing V2", "Mobile App Redesign").
projectCode	string | null	Short identifier used in reporting and integrations (e.g. "PLAT-MIG").
description	string | null	What this project delivers and its business context.
startDate	date (YYYY-MM-DD)	Project start date. Used for resource planning and cost forecasting.
endDate	date (YYYY-MM-DD) | null	Project end date. null = no fixed end date.
ownerUserId	string | null	ID of the Flowstate user who owns/leads this project.
lifecycleStageId	string | null	Current lifecycle stage. References a Lifecycle Stage.
priority	integer	Relative priority. Lower numbers = higher priority. Default: 0.
estimatedCost	number | null	Estimated total cost for the project. Decimal with 2 decimal places.
createdAt	datetime (ISO 8601)	When the record was created. Read-only.
updatedAt	datetime (ISO 8601)	When the record was last modified. Read-only.
customAttributes	array	Custom attribute values for this project. Returned on GET-by-ID. See Custom Attributes.

---

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

External ID Support

The :id path parameter accepts either a Flowstate CUID (e.g. clx1a2b3c4d5e6f7g8h9) or your externalId. The format is auto-detected.

---

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 (1-based).
limit	integer	20	Records per page. Min 1, max 100.
search	string	--	Free-text search by name or description.
sortBy	string	name	Field to sort by.
sortDir	string	asc	Sort direction: 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": "clx7p8r9q0s1t2u3v4w5",
      "externalId": null,
      "name": "Billing V2",
      "projectCode": "BILL-V2",
      "description": "Rebuild the billing system with usage-based pricing support.",
      "startDate": "2026-01-15",
      "endDate": "2026-09-30",
      "ownerUserId": "clx9u1s2e3r4t5y6",
      "lifecycleStageId": "clx2l3c4s5t6u7v8",
      "priority": 1,
      "estimatedCost": 450000.00,
      "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.

---

Create Project

POST /org/:orgId/projects

Create Request Body

Field	Type	Required	Description
name	string	Yes	Project name.
externalId	string | null	No	Your external identifier. Must be unique within the organization. Cannot resemble a CUID format. Max 255 characters.
description	string | null	No	Project description.
projectCode	string | null	No	Short identifier for reporting (e.g. "PLAT-MIG").
startDate	date (YYYY-MM-DD)	Yes	Project start date.
endDate	date (YYYY-MM-DD) | null	No	Project end date. null = no fixed end date.
ownerUserId	string | null	No	ID of the project owner (Flowstate user).
valueStreamId	string | null	No	Value Stream this project belongs to.
lifecycleStageId	string | null	No	Lifecycle Stage ID.
estimatedCost	number | null	No	Estimated total cost. Must be >= 0.
icon	string | null	No	Icon identifier for UI display.
iconColor	string	No	Hex colour code for the icon. Default: "#6B7280".
priority	integer	No	Relative priority (lower = higher). Default: 0.

Update Request Body

All fields from Create are accepted, all optional. You can set or update the externalId field.

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",
    "lifecycleStageId": "clx2l3c4s5t6u7v8",
    "estimatedCost": 320000,
    "priority": 2
  }'

Status: 201 Created

---

Update Project

PATCH /org/:orgId/projects/:id

Updates one or more fields. Only include the fields you want to change.

Example Request

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

---

Delete Project

DELETE /org/:orgId/projects/:id

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

Status: 204 No Content

---

External IDs

You can assign your own externalId during creation or update. This allows you to reference projects by your system's identifier instead of the Flowstate CUID.

• Setting: Pass externalId in the POST or PATCH request body.
• Lookups: Use the external ID directly in path parameters (e.g. GET /projects/MY-EXT-ID).
• Uniqueness: External IDs must be unique per entity type within your organization.
• Format restriction: External IDs cannot match the CUID format (25 lowercase alphanumeric characters starting with a letter).

---

Error Responses

Validation Error (400)

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

Not Found (404)

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

---

Related Endpoints

• Assignments -- Allocate employees, contractors, vacancies, and teams to projects.
• Lifecycle Stages -- The stages a project progresses through.
• Value Streams -- Business capability groupings for projects.
• Teams -- Teams that can be allocated to projects.
• Custom Attributes -- Manage custom fields on projects.