Mentor Status Repository - API Contract

GET /api/v1/mentor-statuses/api/v1/mentor-statuses

List all mentor status records (audit log)

Public

Response Example

{
  "data": [
    {
      "mentor_status_id": "msr_A1B2C3D4",
      "mentor_id": "mntr_01HX4V2K8P",
      "status": "active",
      "reason": null,
      "changed_at": "2026-03-10T09:00:00Z",
      "changed_by": "user_coord_99XZ"
    },
    {
      "mentor_status_id": "msr_E5F6G7H8",
      "mentor_id": "mntr_02BY7M3RL",
      "status": "paused",
      "reason": "Certification expired",
      "changed_at": "2026-03-02T01:00:03Z",
      "changed_by": "system_auto_pause"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 94
  }
}

GET /api/v1/mentor-statuses/api/v1/mentor-statuses/:id

Get a single mentor status record

Public

Response Example

{
  "mentor_status_id": "msr_A1B2C3D4",
  "mentor_id": "mntr_01HX4V2K8P",
  "status": "active",
  "reason": null,
  "changed_at": "2026-03-10T09:00:00Z",
  "changed_by": "user_coord_99XZ",
  "previous_status": "paused",
  "created_at": "2026-03-10T09:00:00Z"
}

POST /api/v1/mentor-statuses/api/v1/mentor-statuses

Write a new status change record

Public

Request Example

{
  "mentor_id": "mntr_01HX4V2K8P",
  "status": "paused",
  "reason": "Personal leave",
  "changed_by": "user_coord_99XZ"
}

Response Example

{
  "mentor_status_id": "msr_Z9Y8X7W6",
  "mentor_id": "mntr_01HX4V2K8P",
  "status": "paused",
  "reason": "Personal leave",
  "changed_by": "user_coord_99XZ",
  "changed_at": "2026-03-26T09:15:00Z",
  "created_at": "2026-03-26T09:15:00Z"
}

PUT /api/v1/mentor-statuses/api/v1/mentor-statuses/:id

Update a status record (e.g. correct reason text)

Public

Request Example

{
  "reason": "Personal leave — extended by 2 weeks"
}

Response Example

{
  "mentor_status_id": "msr_Z9Y8X7W6",
  "reason": "Personal leave — extended by 2 weeks",
  "updated_at": "2026-03-26T10:00:00Z"
}

DELETE /api/v1/mentor-statuses/api/v1/mentor-statuses/:id

Delete a status record

Public

Response Example

{
  "mentor_status_id": "msr_Z9Y8X7W6",
  "deleted": true,
  "deleted_at": "2026-03-26T11:00:00Z"
}

GET /api/v1/mentor-statuses/api/v1/chapters/:chapter_id/mentors/active

List active, assignment-eligible mentors in a chapter

Public

Response Example

{
  "data": [
    {
      "mentor_id": "mntr_01HX4V2K8P",
      "full_name": "Sarah Chen",
      "chapter_id": "chpt_03AZ",
      "status": "active",
      "is_eligible_for_assignment": true
    },
    {
      "mentor_id": "mntr_05DF9N2QW",
      "full_name": "Amara Diallo",
      "chapter_id": "chpt_03AZ",
      "status": "active",
      "is_eligible_for_assignment": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 31
  }
}

GET /api/v1/mentor-statuses/api/v1/chapters/:chapter_id/mentors/paused

List paused mentors in a chapter

Public

Response Example

{
  "data": [
    {
      "mentor_id": "mntr_02BY7M3RL",
      "full_name": "James Okafor",
      "chapter_id": "chpt_03AZ",
      "status": "paused",
      "paused_at": "2026-03-02T01:00:03Z",
      "pause_reason": "Certification expired",
      "is_eligible_for_assignment": false
    }
  ],
  "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"
}