Drivers

Manage project driver types used to categorize and measure project business drivers. Drivers define the metrics that justify project investment (e.g. "Revenue Impact", "Customer Satisfaction", "Technical Debt Reduction").

Driver Object

Field	Type	Description
id	string	Unique identifier (CUID format). System-generated. Read-only.
name	string	Driver name (e.g. "Revenue Impact").
description	string | null	Description of what this driver measures.
isActive	boolean	Whether this driver is active.
sortOrder	integer	Display ordering weight. Lower values appear first.
createdAt	datetime (ISO 8601)	When the record was created. Read-only.
updatedAt	datetime (ISO 8601)	When the record was last modified. Read-only.

---

Endpoints

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

---

List Drivers

GET /org/:orgId/drivers

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}/drivers?sortBy=name" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx6t7u8v9w0x1y2z3a4",
      "name": "Revenue Impact",
      "category": "financial",
      "measurementType": "currency",
      "description": "Expected revenue contribution",
      "icon": "dollar-sign",
      "color": "#10B981",
      "isActive": true,
      "sortOrder": 0,
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2025-11-20T14:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 6,
    "hasNextPage": false
  }
}

---

Create Driver

POST /org/:orgId/drivers

Create Request Body

Field	Type	Required	Description
name	string	Yes	Driver name.
category	string	Yes	Category grouping (e.g. "financial", "customer", "operational").
measurementType	string	Yes	How this driver is measured (e.g. "currency", "percentage", "number").
description	string | null	No	Description.
icon	string | null	No	Icon identifier for UI display.
color	string	No	Hex colour for UI display. Default: "#6B7280".
isActive	boolean	No	Default: true.
sortOrder	integer	No	Display ordering. Default: 0.

Update Request Body

All fields from Create are accepted, all optional.

Example Request

curl -X POST "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/drivers" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Revenue Impact",
    "category": "financial",
    "measurementType": "currency",
    "description": "Expected revenue contribution"
  }'

Status: 201 Created

---

Error Responses

Validation Error (400)

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

Not Found (404)

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

---

Related Endpoints

• Projects -- Projects can have driver values associated with them.