Drivers

Manage project driver types used to categorize and measure project business drivers.

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

Returns a paginated list of drivers 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}/drivers?sortBy=name&limit=50" \
  -H "Authorization: Bearer private_..."

Example Response

{
  "data": [
    {
      "id": "clx6t7u8v9w0x1y2",
      "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"
    },
    {
      "id": "clx1e2n3g4r5o0t6",
      "name": "Customer Satisfaction",
      "category": "customer",
      "measurementType": "percentage",
      "description": "Impact on NPS and customer satisfaction scores",
      "icon": "smile",
      "color": "#8B5CF6",
      "isActive": true,
      "sortOrder": 1,
      "createdAt": "2024-01-05T08:00:00Z",
      "updatedAt": "2025-09-01T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 6,
    "hasNextPage": false
  }
}

---

Get Driver

GET /org/:orgId/drivers/:id

Returns a single driver by ID.

Example Request

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

Example Response

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

---

Create Driver

POST /org/:orgId/drivers

Creates a new driver.

Request Body

{
  "name": "Revenue Impact",
  "category": "financial",
  "measurementType": "currency",
  "description": "Expected revenue contribution"
}

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

Example Response

{
  "data": {
    "id": "clx3d4e5f6g7h8i9",
    "name": "Revenue Impact",
    "category": "financial",
    "measurementType": "currency",
    "description": "Expected revenue contribution",
    "icon": null,
    "color": "#6B7280",
    "isActive": true,
    "sortOrder": 0,
    "createdAt": "2026-03-11T09:40:00Z",
    "updatedAt": "2026-03-11T09:40:00Z"
  }
}

Status: 201 Created

---

Update Driver

PATCH /org/:orgId/drivers/:id

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

Example Request

curl -X PATCH "https://{tenant}.flowstate.inc/api/v1/org/{orgId}/drivers/clx6t7u8v9w0x1y2" \
  -H "Authorization: Bearer private_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Revenue Growth Impact",
    "description": "Expected contribution to annual recurring revenue."
  }'

Example Response

{
  "data": {
    "id": "clx6t7u8v9w0x1y2",
    "name": "Revenue Growth Impact",
    "category": "financial",
    "measurementType": "currency",
    "description": "Expected contribution to annual recurring revenue.",
    "icon": "dollar-sign",
    "color": "#10B981",
    "isActive": true,
    "sortOrder": 0,
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2026-03-11T09:45:00Z"
  }
}

---

Delete Driver

DELETE /org/:orgId/drivers/:id

Deletes a driver. Drivers 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}/drivers/clx6t7u8v9w0x1y2" \
  -H "Authorization: Bearer private_..."

Example Response

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

Status: 200 OK

---

Field Reference

Field	Type	Required	Description
id	string	—	Unique identifier (read-only)
name	string	Yes	Driver name
category	string	Yes	Driver category (e.g., "financial", "customer", "operational")
measurementType	string	Yes	How the driver is measured (e.g., "currency", "percentage", "number")
description	string	No	Driver description
icon	string	No	Icon identifier for UI display
color	string	No	Hex color for UI display (default: "#6B7280")
isActive	boolean	No	Whether the driver is active (default: true)
sortOrder	integer	No	Display sort order (default: 0)
createdAt	datetime	—	Record creation timestamp (read-only)
updatedAt	datetime	—	Last modification timestamp (read-only)