KPIs
KPIs and their values over time.
GET
/v1/kpisList KPIs
Active KPIs on the scorecard that you can see, with their goal, owner and team.
Needs
kpis:readMCP tool list_kpisQuery parameters
team_idstring or nullA team's KPIs plus the org-wide ones
Response
datalist of KpiRequired
curl "https://developers.playbookops.ai/v1/kpis" \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"Response · 200
{
"data": [
{
"id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
"name": "Ana Ruiz",
"description": "Confirm the date and ask about parking.",
"unit": "percent",
"frequency": "monthly",
"goal": 0,
"goal_direction": "above",
"owner_name": "Ana Ruiz",
"team_name": "Operations"
}
]
}GET
/v1/kpis/{kpi_id}/valuesGet a KPI's values
A KPI's recorded values by period, oldest first.
Needs
kpis:readMCP tool get_kpi_valuesPath parameters
kpi_idstringRequired
Query parameters
sincestring (date) or nullPeriods starting on or after this day
untilstring (date) or nullPeriods starting on or before this day
Response
kpi_idstringRequireddatalist of KpiValueRequired
curl "https://developers.playbookops.ai/v1/kpis/KPI_ID/values" \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"Response · 200
{
"kpi_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
"data": [
{
"period_start": "2026-11-21",
"value": 0,
"note": "Up after the spring campaign"
}
]
}PUT
/v1/kpis/{kpi_id}/values/{period}Record a KPI value
Record or correct a KPI's value for one period, replacing what was there. Only the KPI's owner or an org admin can, and only for KPIs that are entered by hand.
Needs
kpis:writeChanges data · supports Idempotency-KeyMCP tool record_kpi_valuePath parameters
kpi_idstringRequiredperiodstringRequired
Body
valuenumberRequirednotestring or nullReplaces the period's note; leave it out to clear it
Up to 1,000 characters.
Response
period_startstring (date)Requiredvaluenumber or nullnotestring or null
curl -X PUT "https://developers.playbookops.ai/v1/kpis/KPI_ID/values/PERIOD" \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"value": 0
}'Response · 200
{
"period_start": "2026-11-21",
"value": 0,
"note": "Up after the spring campaign"
}DELETE
/v1/kpis/{kpi_id}/values/{period}Clear a KPI value
Remove a KPI's value and note for one period, so the period shows as not entered. Same rules as record_kpi_value.
Needs
kpis:writeChanges data · supports Idempotency-KeyMCP tool clear_kpi_valuePath parameters
kpi_idstringRequiredperiodstringRequired
Response
kpi_idstringRequiredperiod_startstring (date)RequireddeletedbooleanDefault true.
curl -X DELETE "https://developers.playbookops.ai/v1/kpis/KPI_ID/values/PERIOD" \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Response · 200
{
"kpi_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
"period_start": "2026-11-21",
"deleted": true
}