KPIs

KPIs and their values over time.

GET/v1/kpis

List KPIs

Active KPIs on the scorecard that you can see, with their goal, owner and team.

Needs kpis:readMCP tool list_kpis

Query parameters

  • team_idstring or null

    A 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}/values

Get a KPI's values

A KPI's recorded values by period, oldest first.

Needs kpis:readMCP tool get_kpi_values

Path parameters

  • kpi_idstringRequired

Query parameters

  • sincestring (date) or null

    Periods starting on or after this day

  • untilstring (date) or null

    Periods starting on or before this day

Response

  • kpi_idstringRequired
  • datalist 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_value

Path parameters

  • kpi_idstringRequired
  • periodstringRequired

Body

  • valuenumberRequired
  • notestring or null

    Replaces the period's note; leave it out to clear it

    Up to 1,000 characters.

Response

  • period_startstring (date)Required
  • valuenumber or null
  • notestring 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_value

Path parameters

  • kpi_idstringRequired
  • periodstringRequired

Response

  • kpi_idstringRequired
  • period_startstring (date)Required
  • deletedboolean

    Default 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
}