Mentor Status Service - API Contract

GET /api/v1/mentors/api/v1/mentors

List mentors with optional status/chapter filter

Public

Response Example

{
  "data": [
    {
      "mentor_id": "mntr_01HX4V2K8P",
      "full_name": "Sarah Chen",
      "chapter_id": "chpt_03AZ",
      "status": "active",
      "paused_at": null,
      "pause_reason": null,
      "is_eligible_for_assignment": true
    },
    {
      "mentor_id": "mntr_02BY7M3RL",
      "full_name": "James Okafor",
      "chapter_id": "chpt_03AZ",
      "status": "paused",
      "paused_at": "2026-03-10T08:00:00Z",
      "pause_reason": "Certification expired",
      "is_eligible_for_assignment": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47
  }
}

GET /api/v1/mentors/api/v1/mentors/:id

Get a mentor's full status details

Public

Response Example

{
  "mentor_id": "mntr_01HX4V2K8P",
  "full_name": "Sarah Chen",
  "chapter_id": "chpt_03AZ",
  "email": "sarah.chen@example.org",
  "status": "active",
  "is_eligible_for_assignment": true,
  "paused_at": null,
  "pause_reason": null,
  "reactivated_at": "2026-03-10T09:00:00Z",
  "certification_expiry": "2027-06-15",
  "created_at": "2024-09-01T10:00:00Z",
  "updated_at": "2026-03-10T09:00:00Z"
}

POST /api/v1/mentors/api/v1/mentors

Register a new mentor

Public

Request Example

{
  "full_name": "Amara Diallo",
  "email": "amara.diallo@example.org",
  "chapter_id": "chpt_03AZ",
  "certification_expiry": "2027-09-30"
}

Response Example

{
  "mentor_id": "mntr_05DF9N2QW",
  "full_name": "Amara Diallo",
  "email": "amara.diallo@example.org",
  "chapter_id": "chpt_03AZ",
  "status": "active",
  "is_eligible_for_assignment": true,
  "certification_expiry": "2027-09-30",
  "created_at": "2026-03-26T11:00:00Z"
}

PUT /api/v1/mentors/api/v1/mentors/:id

Update mentor profile fields

Public

Request Example

{
  "full_name": "Sarah Chen-Williams",
  "certification_expiry": "2028-06-15"
}

Response Example

{
  "mentor_id": "mntr_01HX4V2K8P",
  "full_name": "Sarah Chen-Williams",
  "certification_expiry": "2028-06-15",
  "updated_at": "2026-03-26T11:10:00Z"
}

DELETE /api/v1/mentors/api/v1/mentors/:id

Soft-delete a mentor record

Public

Response Example

{
  "mentor_id": "mntr_01HX4V2K8P",
  "deleted": true,
  "deleted_at": "2026-03-26T11:15:00Z"
}

POST /api/v1/mentors/api/v1/mentors/:id/pause

Pause an active mentor (manual)

Public

Request Example

{
  "reason": "Personal leave — returning approximately 4 weeks",
  "initiated_by": "user_coord_99XZ"
}

Response Example

{
  "mentor_id": "mntr_01HX4V2K8P",
  "status": "paused",
  "paused_at": "2026-03-26T09:15:00Z",
  "pause_reason": "Personal leave — returning approximately 4 weeks",
  "is_eligible_for_assignment": false
}

POST /api/v1/mentors/api/v1/mentors/:id/reactivate

Reactivate a paused mentor

Public

Request Example

{
  "initiated_by": "user_coord_99XZ"
}

Response Example

{
  "mentor_id": "mntr_01HX4V2K8P",
  "status": "active",
  "reactivated_at": "2026-03-26T09:20:00Z",
  "is_eligible_for_assignment": true
}

GET /api/v1/mentors/api/v1/mentors/:id/eligibility

Check assignment eligibility for a mentor

Public

Response Example

{
  "mentor_id": "mntr_01HX4V2K8P",
  "is_eligible_for_assignment": true,
  "status": "active",
  "reasons_ineligible": []
}

Additional Metadata

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