Stats Repository - API Contract

GET /api/v1/stats/api/v1/stats/peer-mentor

List peer mentor stats snapshots with pagination

Public

Response Example

{
  "data": [
    {
      "user_id": "usr_4f8a2c",
      "total_activities": 47,
      "completed_activities": 42,
      "pending_activities": 5,
      "hours_logged": 128.5,
      "time_window": "quarterly",
      "start_date": "2026-01-01",
      "end_date": "2026-03-26",
      "generated_at": "2026-03-26T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /api/v1/stats/api/v1/stats/peer-mentor/:userId

Get stats snapshot for a specific peer mentor

Public

Response Example

{
  "user_id": "usr_4f8a2c",
  "total_activities": 47,
  "completed_activities": 42,
  "pending_activities": 5,
  "hours_logged": 128.5,
  "time_window": "quarterly",
  "start_date": "2026-01-01",
  "end_date": "2026-03-26",
  "generated_at": "2026-03-26T10:00:00Z"
}

POST /api/v1/stats/api/v1/stats/peer-mentor

Request a fresh stats snapshot for a peer mentor

Public

Request Example

{
  "user_id": "usr_4f8a2c",
  "time_window": "quarterly",
  "start_date": "2026-01-01",
  "end_date": "2026-03-26"
}

Response Example

{
  "user_id": "usr_4f8a2c",
  "total_activities": 47,
  "completed_activities": 42,
  "pending_activities": 5,
  "hours_logged": 128.5,
  "time_window": "quarterly",
  "start_date": "2026-01-01",
  "end_date": "2026-03-26",
  "generated_at": "2026-03-26T10:05:00Z"
}

PUT /api/v1/stats/api/v1/stats/peer-mentor/:userId

Update/recalculate a peer mentor stats snapshot

Public

Request Example

{
  "time_window": "monthly",
  "start_date": "2026-03-01",
  "end_date": "2026-03-26"
}

Response Example

{
  "user_id": "usr_4f8a2c",
  "total_activities": 18,
  "completed_activities": 16,
  "pending_activities": 2,
  "hours_logged": 44,
  "time_window": "monthly",
  "start_date": "2026-03-01",
  "end_date": "2026-03-26",
  "generated_at": "2026-03-26T10:06:00Z"
}

DELETE /api/v1/stats/api/v1/stats/peer-mentor/:userId

Delete cached stats snapshot for a peer mentor

Public

Response Example

{
  "deleted": true,
  "user_id": "usr_4f8a2c"
}

GET /api/v1/stats/api/v1/stats/coordinator

List coordinator chapter stats snapshots

Public

Response Example

{
  "data": [
    {
      "coordinator_id": "usr_coord_9b1c",
      "chapter_ids": [
        "chp_oslo_01",
        "chp_bergen_03"
      ],
      "total_activities": 213,
      "completed_activities": 198,
      "pending_activities": 15,
      "hours_logged": 614,
      "time_window": "quarterly",
      "start_date": "2026-01-01",
      "end_date": "2026-03-26",
      "generated_at": "2026-03-26T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /api/v1/stats/api/v1/stats/coordinator/:coordinatorId

Get stats snapshot for a specific coordinator across their chapters

Public

Response Example

{
  "coordinator_id": "usr_coord_9b1c",
  "chapter_ids": [
    "chp_oslo_01",
    "chp_bergen_03"
  ],
  "total_activities": 213,
  "completed_activities": 198,
  "pending_activities": 15,
  "hours_logged": 614,
  "time_window": "quarterly",
  "start_date": "2026-01-01",
  "end_date": "2026-03-26",
  "generated_at": "2026-03-26T10:00:00Z"
}

GET /api/v1/stats/api/v1/stats/coordinator/:coordinatorId/breakdown

Get per-peer-mentor breakdown rows for a coordinator's scope

Public

Response Example

{
  "data": [
    {
      "user_id": "usr_4f8a2c",
      "full_name": "Anna Johansson",
      "chapter_id": "chp_oslo_01",
      "chapter_name": "Oslo Sør",
      "total_activities": 14,
      "hours_logged": 38.5,
      "last_activity_date": "2026-03-20"
    },
    {
      "user_id": "usr_7d3e1b",
      "full_name": "Erik Nilsen",
      "chapter_id": "chp_bergen_03",
      "chapter_name": "Bergen Nord",
      "total_activities": 9,
      "hours_logged": 22,
      "last_activity_date": "2026-03-18"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

GET /api/v1/stats/api/v1/stats/peer-mentor/:userId/chart

Get time-series chart data points for a peer mentor

Public

Response Example

{
  "data": [
    {
      "date": "2026-03-01",
      "value": 3.5
    },
    {
      "date": "2026-03-08",
      "value": 5
    },
    {
      "date": "2026-03-15",
      "value": 4
    },
    {
      "date": "2026-03-22",
      "value": 6.5
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 4
  }
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}