Projects

A project is a piece of work that people, contractors, vacancies and teams are allocated to. Use these endpoints to keep projects in step with another system; allocate capacity to them with Assignments.

All paths are under https://{tenant}.flowstate.inc/api/v1.

:id accepts a Flowstate id or your externalId. A value that looks like a Flowstate id (24 or 25 lowercase letters and digits, starting with a letter) is looked up as an id; anything else as an externalId.

The project object

Responses can carry further fields that aren’t listed here. Don’t depend on them.

List projects

GET /org/:orgId/projects

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

{
  "data": [
    {
      "id": "clx7p8r9q0s1t2u3v4w5x6y7z",
      "externalId": "JIRA-BILL",
      "name": "Billing V2",
      "projectCode": "BILL-V2",
      "description": "Usage-based pricing for the billing system.",
      "status": "IN_PROGRESS",
      "priority": 1,
      "startDate": "2026-01-15T00:00:00.000Z",
      "endDate": "2026-09-30T00:00:00.000Z",
      "ownerUserId": "clx9u1s2e3r4t5y6u7i8o9p0a",
      "valueStreamId": null,
      "costCentreId": "clx3c4c5e6n7t8r9e0a1b2c3d",
      "initiativeId": null,
      "estimatedCost": "450000",
      "icon": null,
      "iconColor": "#6B7280",
      "createdAt": "2025-11-01T09:00:00.000Z",
      "updatedAt": "2026-02-15T16:30:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 10, "total": 1, "hasNextPage": false }
}

Retrieve a project

GET /org/:orgId/projects/:id

Returns the project object with customAttributes.

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

Create a project

POST /org/:orgId/projects

Unknown fields are ignored.

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",
    "externalId": "JIRA-MOB",
    "projectCode": "MOB-RD",
    "startDate": "2026-04-01",
    "endDate": "2026-12-31",
    "estimatedCost": 320000,
    "priority": 2
  }'

201 Created with the project object. A new project starts in BACKLOG.

Update a project

PATCH /org/:orgId/projects/:id

Takes the same fields as create, all optional. Send only what changes; send null to clear a nullable field.

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/projects/JIRA-MOB" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{ "endDate": "2027-02-26", "priority": 1 }'

200 OK with the updated project.

Delete a project

DELETE /org/:orgId/projects/:id

Deletes the project, every allocation to it and the effort recorded against it. This can’t be undone.

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

Errors

scenarioId on a read is validated but returns live data. See Errors for the error body.

Webhooks

Creates, updates and deletes made here send project events. See Webhooks.

Related

• Assignments: allocate people and teams to a project.
• Custom attributes: your own fields on projects.