Annual Stats Aggregation Service - API Contract

GET /api/v1/annual-summaries/api/v1/annual-summaries

List annual summaries across mentors (admin use)

Public

Response Example

{
  "data": [
    {
      "mentor_id": "mentor_001",
      "period": {
        "year": 2025,
        "start_date": "2025-01-01",
        "end_date": "2025-12-31"
      },
      "total_hours": 312.5,
      "unique_contacts_helped": 47,
      "activity_count": 198,
      "computed_at": "2026-01-02T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /api/v1/annual-summaries/api/v1/annual-summaries/:mentor_id

Get full annual summary for a specific mentor and period

Public

Response Example

{
  "mentor_id": "mentor_001",
  "period": {
    "year": 2025,
    "start_date": "2025-01-01",
    "end_date": "2025-12-31"
  },
  "total_hours": 312.5,
  "unique_contacts_helped": 47,
  "activity_count": 198,
  "activity_type_breakdown": [
    {
      "activity_type": "one_on_one",
      "count": 120,
      "hours": 180,
      "percentage": 57.6
    },
    {
      "activity_type": "group_session",
      "count": 45,
      "hours": 90,
      "percentage": 28.8
    },
    {
      "activity_type": "written_feedback",
      "count": 33,
      "hours": 42.5,
      "percentage": 13.6
    }
  ],
  "computed_at": "2026-01-02T08:00:00Z"
}

POST /api/v1/annual-summaries/api/v1/annual-summaries

Trigger computation of an annual summary for a mentor and period

Public

Request Example

{
  "mentor_id": "mentor_001",
  "period": {
    "year": 2025,
    "start_date": "2025-01-01",
    "end_date": "2025-12-31"
  }
}

Response Example

{
  "mentor_id": "mentor_001",
  "period": {
    "year": 2025,
    "start_date": "2025-01-01",
    "end_date": "2025-12-31"
  },
  "total_hours": 312.5,
  "unique_contacts_helped": 47,
  "activity_count": 198,
  "activity_type_breakdown": [
    {
      "activity_type": "one_on_one",
      "count": 120,
      "hours": 180,
      "percentage": 57.6
    }
  ],
  "computed_at": "2026-01-02T08:00:00Z"
}

PUT /api/v1/annual-summaries/api/v1/annual-summaries/:mentor_id

Recompute and update annual summary for a mentor (force refresh)

Public

Request Example

{
  "period": {
    "year": 2025,
    "start_date": "2025-01-01",
    "end_date": "2025-12-31"
  },
  "force_recompute": true
}

Response Example

{
  "mentor_id": "mentor_001",
  "period": {
    "year": 2025,
    "start_date": "2025-01-01",
    "end_date": "2025-12-31"
  },
  "total_hours": 315,
  "unique_contacts_helped": 48,
  "activity_count": 200,
  "activity_type_breakdown": [
    {
      "activity_type": "one_on_one",
      "count": 122,
      "hours": 182,
      "percentage": 57.8
    }
  ],
  "computed_at": "2026-01-03T10:15:00Z"
}

DELETE /api/v1/annual-summaries/api/v1/annual-summaries/:mentor_id

Delete a computed annual summary for a mentor

Public

Response Example

{
  "deleted": true,
  "mentor_id": "mentor_001",
  "year": 2025
}

GET /api/v1/annual-summaries/api/v1/annual-summaries/:mentor_id/activity-breakdown

Get activity type breakdown for a mentor's annual period

Public

Response Example

{
  "data": [
    {
      "activity_type": "one_on_one",
      "count": 120,
      "hours": 180,
      "percentage": 57.6
    },
    {
      "activity_type": "group_session",
      "count": 45,
      "hours": 90,
      "percentage": 28.8
    },
    {
      "activity_type": "written_feedback",
      "count": 33,
      "hours": 42.5,
      "percentage": 13.6
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3
  }
}

GET /api/v1/annual-summaries/api/v1/annual-summaries/:mentor_id/total-hours

Get total hours logged for a mentor in a given period

Public

Response Example

{
  "mentor_id": "mentor_001",
  "period": {
    "year": 2025
  },
  "total_hours": 312.5
}

GET /api/v1/annual-summaries/api/v1/annual-summaries/:mentor_id/unique-contacts

Get count of unique contacts helped by a mentor in a given period

Public

Response Example

{
  "mentor_id": "mentor_001",
  "period": {
    "year": 2025
  },
  "unique_contacts_helped": 47
}

Additional Metadata

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