Milestone Detection Service - API Contract

GET /api/v1/milestones/api/v1/milestones

List all known milestones with optional filters

Public

Response Example

{
  "data": [
    {
      "id": "milestone_100h",
      "mentor_id": "mentor_001",
      "name": "100 Hours Milestone",
      "type": "hours_logged",
      "status": "achieved",
      "threshold": 100,
      "achieved_value": 312.5,
      "achieved_at": "2025-07-14T16:30:00Z",
      "accessibility_label": "You reached 100 hours of mentoring on July 14, 2025"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5
  }
}

GET /api/v1/milestones/api/v1/milestones/:id

Get details of a single milestone

Public

Response Example

{
  "id": "milestone_100h",
  "mentor_id": "mentor_001",
  "name": "100 Hours Milestone",
  "type": "hours_logged",
  "status": "achieved",
  "threshold": 100,
  "achieved_value": 312.5,
  "achieved_at": "2025-07-14T16:30:00Z",
  "accessibility_label": "You reached 100 hours of mentoring on July 14, 2025",
  "badge_image_url": "/assets/badges/100h.png"
}

POST /api/v1/milestones/api/v1/milestones

Detect and persist milestones for a mentor based on their annual summary

Public

Request Example

{
  "mentor_id": "mentor_001",
  "period": {
    "year": 2025,
    "start_date": "2025-01-01",
    "end_date": "2025-12-31"
  },
  "summary": {
    "total_hours": 312.5,
    "unique_contacts_helped": 47,
    "activity_count": 198
  }
}

Response Example

{
  "data": [
    {
      "id": "milestone_100h",
      "mentor_id": "mentor_001",
      "name": "100 Hours Milestone",
      "type": "hours_logged",
      "status": "achieved",
      "threshold": 100,
      "achieved_value": 312.5,
      "achieved_at": "2025-07-14T16:30:00Z",
      "accessibility_label": "You reached 100 hours of mentoring on July 14, 2025"
    },
    {
      "id": "milestone_50contacts",
      "mentor_id": "mentor_001",
      "name": "50 Unique Contacts",
      "type": "contacts_helped",
      "status": "in_progress",
      "threshold": 50,
      "achieved_value": 47,
      "progress_percentage": 94,
      "accessibility_label": "You have helped 47 out of 50 unique contacts"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

PUT /api/v1/milestones/api/v1/milestones/:id

Update milestone status or metadata

Public

Request Example

{
  "status": "achieved",
  "achieved_value": 315,
  "achieved_at": "2026-01-03T09:00:00Z"
}

Response Example

{
  "id": "milestone_300h",
  "mentor_id": "mentor_001",
  "name": "300 Hours Milestone",
  "type": "hours_logged",
  "status": "achieved",
  "threshold": 300,
  "achieved_value": 315,
  "achieved_at": "2026-01-03T09:00:00Z",
  "accessibility_label": "You reached 300 hours of mentoring on January 3, 2026"
}

DELETE /api/v1/milestones/api/v1/milestones/:id

Remove a milestone record

Public

Response Example

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

GET /api/v1/milestones/api/v1/milestones/:mentor_id/new

Get newly achieved milestones for a mentor in a given period

Public

Response Example

{
  "data": [
    {
      "id": "milestone_300h",
      "mentor_id": "mentor_001",
      "name": "300 Hours Milestone",
      "type": "hours_logged",
      "status": "achieved",
      "threshold": 300,
      "achieved_value": 312.5,
      "achieved_at": "2025-11-22T14:00:00Z",
      "accessibility_label": "You reached 300 hours of mentoring on November 22, 2025"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /api/v1/milestones/api/v1/milestones/:mentor_id/in-progress

Get milestones currently in progress for a mentor

Public

Response Example

{
  "data": [
    {
      "id": "milestone_50contacts",
      "mentor_id": "mentor_001",
      "name": "50 Unique Contacts",
      "type": "contacts_helped",
      "status": "in_progress",
      "threshold": 50,
      "current_value": 47,
      "progress_percentage": 94,
      "remaining": 3,
      "accessibility_label": "You have helped 47 out of 50 unique contacts, 3 remaining"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

Additional Metadata

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