KPIs API
API endpoints for managing KPI definitions, values, targets, and SQCDP categorization.
Overview
KPIs (Key Performance Indicators) provide real-time metrics tracking on boards. Each KPI has a definition with thresholds, belongs to a SQCDP category, and stores time-series values. Threshold breaches automatically generate alerts.
Define KPI
Create a new KPI definition on a board.
POST /api/trpc/kpis.define
Request:
{
"json": {
"boardId": "brd_01HXK5...",
"name": "On-Time Delivery Rate",
"category": "delivery",
"unit": "%",
"direction": "higher_is_better",
"frequency": "weekly",
"thresholds": {
"green": { "min": 95 },
"amber": { "min": 85, "max": 94.99 },
"red": { "max": 84.99 }
},
"responsibleUserId": "usr_01HXK5..."
}
}
| Field | Type | Required | Description |
|---|---|---|---|
boardId | string | Yes | Board to attach the KPI to |
name | string | Yes | KPI name (1-200 characters) |
category | string | Yes | SQCDP category: safety, quality, cost, delivery, people |
unit | string | No | Display unit (%, days, count, custom) |
direction | string | Yes | higher_is_better or lower_is_better |
frequency | string | Yes | daily, weekly, monthly, quarterly |
thresholds | object | No | Green/amber/red threshold ranges |
responsibleUserId | string | No | User responsible for this KPI |
Update KPI
POST /api/trpc/kpis.update
{
"json": {
"id": "kpi_01HXK5...",
"name": "OTD Rate",
"thresholds": {
"green": { "min": 90 },
"amber": { "min": 80, "max": 89.99 },
"red": { "max": 79.99 }
}
}
}
Delete KPI
Deletes the KPI definition and all associated values, targets, and alerts.
POST /api/trpc/kpis.delete
{
"json": {
"id": "kpi_01HXK5..."
}
}
Deleting a KPI cascades to all stored values, targets, and alert history. This action cannot be undone.
List KPIs
List all KPIs for a board with their latest values.
GET /api/trpc/kpis.list?input={"json":{"boardId":"brd_01HXK5..."}}
Response:
{
"result": {
"data": {
"json": {
"kpis": [
{
"id": "kpi_01HXK5...",
"name": "On-Time Delivery Rate",
"category": "delivery",
"unit": "%",
"direction": "higher_is_better",
"frequency": "weekly",
"latestValue": {
"value": 96.5,
"status": "green",
"recordedAt": "2026-03-20T08:00:00.000Z"
},
"target": { "value": 95, "deadline": "2026-06-30" },
"responsibleUser": {
"id": "usr_01HXK5...",
"name": "Alice Johnson"
}
}
]
}
}
}
}
List by Category
Group KPIs by SQCDP category for dashboard rendering.
GET /api/trpc/kpis.listByCategory?input={"json":{"boardId":"brd_01HXK5..."}}
Response:
{
"result": {
"data": {
"json": {
"safety": [ { "id": "kpi_01HXK5...", "name": "Incident Rate", "latestValue": { "value": 0, "status": "green" } } ],
"quality": [ { "id": "kpi_01HXK6...", "name": "Defect Rate", "latestValue": { "value": 2.1, "status": "amber" } } ],
"cost": [],
"delivery": [ { "id": "kpi_01HXK7...", "name": "OTD Rate", "latestValue": { "value": 96.5, "status": "green" } } ],
"people": []
}
}
}
}
Get Value
Retrieve the latest value for a KPI.
GET /api/trpc/kpis.getValue?input={"json":{"kpiId":"kpi_01HXK5..."}}
Get History
Retrieve time-series data for a KPI.
GET /api/trpc/kpis.getHistory?input={"json":{"kpiId":"kpi_01HXK5...","from":"2026-01-01","to":"2026-03-23","limit":100}}
| Parameter | Type | Required | Description |
|---|---|---|---|
kpiId | string | Yes | KPI ID |
from | string | No | Start date (ISO 8601) |
to | string | No | End date (ISO 8601) |
limit | number | No | Max data points (default: 100) |
Response:
{
"result": {
"data": {
"json": {
"history": [
{ "value": 94.2, "status": "amber", "recordedAt": "2026-03-06T08:00:00.000Z", "recordedBy": "usr_01HXK5..." },
{ "value": 96.5, "status": "green", "recordedAt": "2026-03-13T08:00:00.000Z", "recordedBy": "usr_01HXK5..." },
{ "value": 97.1, "status": "green", "recordedAt": "2026-03-20T08:00:00.000Z", "recordedBy": "usr_01HXK5..." }
]
}
}
}
}
Set Value
Enter a new KPI value. The API automatically evaluates thresholds and generates alerts if breached.
POST /api/trpc/kpis.setValue
{
"json": {
"kpiId": "kpi_01HXK5...",
"value": 82.3,
"comment": "Supplier delays impacted OTD this week"
}
}
When a value breaches a threshold, the system automatically creates an alert and notifies the responsible user. The status field (green, amber, red) is computed server-side based on the KPI’s threshold configuration.
Batch Set Values
Enter multiple KPI values at once (e.g., during a daily stand-up).
POST /api/trpc/kpis.batchSetValues
{
"json": {
"entries": [
{ "kpiId": "kpi_01HXK5...", "value": 96.5 },
{ "kpiId": "kpi_01HXK6...", "value": 2.1, "comment": "Minor uptick in defects" },
{ "kpiId": "kpi_01HXK7...", "value": 0 }
]
}
}
Get Alerts
List threshold breach alerts for a board or specific KPI.
GET /api/trpc/kpis.getAlerts?input={"json":{"boardId":"brd_01HXK5...","status":"active"}}
| Parameter | Type | Required | Description |
|---|---|---|---|
boardId | string | Yes | Board ID |
kpiId | string | No | Filter to a specific KPI |
status | string | No | active, acknowledged, resolved |
Response:
{
"result": {
"data": {
"json": {
"alerts": [
{
"id": "alt_01HXK5...",
"kpiId": "kpi_01HXK5...",
"kpiName": "On-Time Delivery Rate",
"value": 82.3,
"threshold": "red",
"status": "active",
"triggeredAt": "2026-03-20T08:00:00.000Z"
}
]
}
}
}
}
Target Management
Get Targets
GET /api/trpc/kpis.getTargets?input={"json":{"kpiId":"kpi_01HXK5..."}}
Set Target
POST /api/trpc/kpis.setTarget
{
"json": {
"kpiId": "kpi_01HXK5...",
"value": 98,
"deadline": "2026-06-30",
"milestones": [
{ "value": 95, "deadline": "2026-04-30" },
{ "value": 97, "deadline": "2026-05-31" }
]
}
}
| Field | Type | Required | Description |
|---|---|---|---|
kpiId | string | Yes | KPI ID |
value | number | Yes | Target value |
deadline | string | Yes | Target deadline (ISO 8601 date) |
milestones | array | No | Intermediate milestone targets |
Use milestones to track incremental progress toward KPI targets. The SQCDP dashboard will show milestone progress alongside current values.