Scorecards API

Endpoints

`GET /api/scorecards`

List scorecards, scoped by the user’s access level.

Permission: view:scorecards

Query params:

type — weekly or monthly (optional filter by scorecard type)
squad_id — filter to scorecards from users in a specific squad (intersected with access-level scoping)

`POST /api/scorecards`

Create a new scorecard. Weekly scorecards snapshot the user’s checklist template and initialize a metrics row. Monthly scorecards snapshot KPIs from the objectives hierarchy and initialize a metrics row.

Permission: update:scorecards

Body:

{
  "type": "weekly",
  "period_key": "2026-03-02",
  "week_of": "2026-03-02",
  "squad_name": "Squad Alpha"
}

For monthly:

{
  "type": "monthly",
  "period_key": "2026-03"
}

type: "weekly" (default) or "monthly"
period_key: ISO Monday date for weekly (2026-03-02), YYYY-MM for monthly (2026-03)
week_of: Optional, derived from period_key for weekly scorecards

`GET /api/scorecards/available-kpis`

Returns KPI definitions applicable to the current user from the objectives hierarchy, enriched with objective/priority breadcrumb info.

Permission: view:scorecards

`GET /api/scorecards/template-items`

Get checklist template items for the current user’s assigned scorecard template.

Permission: view:scorecards

`GET /api/scorecards/history`

Returns trend data across scorecards for charts. Computes checklist completion percentage, KPI status summary, and financial metrics per scorecard.

Permission: view:scorecards

Query params:

user_id - target user (defaults to current user)
type - weekly or monthly (defaults to weekly)
limit - max entries to return (defaults to 12, max 52)

Response:

{
  "history": [
    {
      "id": "sc-abc",
      "period_key": "2026-03-02",
      "type": "weekly",
      "checklist_completion": 0.85,
      "kpi_summary": { "on-track": 3, "at-risk": 1, "off-track": 0, "pending": 0 },
      "metrics": { "billable": 32, "utilisation": 80, "revenue": 12000, "profit": 25 }
    }
  ]
}

`GET /api/scorecards/monthly-aggregation`

Aggregates weekly scorecard data for a given month. Used by the monthly scorecard’s Weekly Summary card.

Permission: view:scorecards

Query params:

user_id - target user (defaults to current user)
month - YYYY-MM format (required)

Response:

{
  "weekly_count": 4,
  "checklist_average": 0.82,
  "metrics_totals": {
    "billable": 128,
    "utilisation": 80.5,
    "revenue": 48000,
    "profit": 25
  }
}

`GET /api/scorecards/:id`

Get a scorecard with all associated data (scores, KPIs with breadcrumb info, metrics, template items). Returns type and period_key on the scorecard object.

Permission: view:scorecards

`PUT /api/scorecards/:id`

Update a scorecard and its associated data. Full replacement pattern for scores, kpis, and metrics arrays.

Permission: update:scorecards

`DELETE /api/scorecards/:id`

Delete a scorecard and all associated data.

Permission: update:scorecards