Annual Summary Repository - API Contract

GET /api/v1/activities/api/v1/activities

List activities with optional mentor and date range filters

Public

Response Example

{
  "data": [
    {
      "id": "activity_001",
      "mentor_id": "mentor_001",
      "contact_id": "contact_012",
      "activity_type": "one_on_one",
      "duration_hours": 1.5,
      "session_date": "2025-03-15T14:00:00Z",
      "notes_summary": "Reviewed CV, discussed career pivot into data science",
      "created_at": "2025-03-15T15:35:00Z"
    },
    {
      "id": "activity_002",
      "mentor_id": "mentor_001",
      "contact_id": "contact_007",
      "activity_type": "written_feedback",
      "duration_hours": 0.5,
      "session_date": "2025-03-18T09:00:00Z",
      "notes_summary": "Provided feedback on portfolio project",
      "created_at": "2025-03-18T09:35:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 198
  }
}

GET /api/v1/activities/api/v1/activities/:id

Get a single activity record

Public

Response Example

{
  "id": "activity_001",
  "mentor_id": "mentor_001",
  "contact_id": "contact_012",
  "activity_type": "one_on_one",
  "duration_hours": 1.5,
  "session_date": "2025-03-15T14:00:00Z",
  "notes_summary": "Reviewed CV, discussed career pivot into data science",
  "tags": [
    "career",
    "cv_review"
  ],
  "created_at": "2025-03-15T15:35:00Z",
  "updated_at": "2025-03-15T15:35:00Z"
}

POST /api/v1/activities/api/v1/activities

Create a new activity record

Public

Request Example

{
  "mentor_id": "mentor_001",
  "contact_id": "contact_019",
  "activity_type": "group_session",
  "duration_hours": 2,
  "session_date": "2025-04-02T18:00:00Z",
  "notes_summary": "Monthly group check-in, 5 attendees",
  "tags": [
    "group",
    "monthly_checkin"
  ]
}

Response Example

{
  "id": "activity_199",
  "mentor_id": "mentor_001",
  "contact_id": "contact_019",
  "activity_type": "group_session",
  "duration_hours": 2,
  "session_date": "2025-04-02T18:00:00Z",
  "notes_summary": "Monthly group check-in, 5 attendees",
  "tags": [
    "group",
    "monthly_checkin"
  ],
  "created_at": "2025-04-02T20:05:00Z",
  "updated_at": "2025-04-02T20:05:00Z"
}

PUT /api/v1/activities/api/v1/activities/:id

Update an existing activity record

Public

Request Example

{
  "duration_hours": 2.5,
  "notes_summary": "Monthly group check-in, 5 attendees — session ran long",
  "tags": [
    "group",
    "monthly_checkin",
    "extended"
  ]
}

Response Example

{
  "id": "activity_199",
  "mentor_id": "mentor_001",
  "contact_id": "contact_019",
  "activity_type": "group_session",
  "duration_hours": 2.5,
  "session_date": "2025-04-02T18:00:00Z",
  "notes_summary": "Monthly group check-in, 5 attendees — session ran long",
  "tags": [
    "group",
    "monthly_checkin",
    "extended"
  ],
  "created_at": "2025-04-02T20:05:00Z",
  "updated_at": "2025-04-03T08:00:00Z"
}

DELETE /api/v1/activities/api/v1/activities/:id

Delete an activity record

Public

Response Example

{
  "deleted": true,
  "id": "activity_001"
}

GET /api/v1/activities/api/v1/activities/cache/:mentor_id

Get a cached annual summary for a mentor if it exists

Public

Response Example

{
  "mentor_id": "mentor_001",
  "cached": true,
  "period": {
    "year": 2025,
    "start_date": "2025-01-01",
    "end_date": "2025-12-31"
  },
  "total_hours": 312.5,
  "unique_contacts_helped": 47,
  "activity_count": 198,
  "cached_at": "2026-01-02T08:00:00Z"
}

Additional Metadata

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