Coordinator Notification Service - API Contract

GET /api/v1/notifications/api/v1/notifications

List notifications with optional filters

Public

Response Example

{
  "data": [
    {
      "notification_id": "notif_7GH2MX1PQ",
      "recipient_id": "user_coord_99XZ",
      "type": "mentor_status_change",
      "title": "Mentor Sarah Chen has been paused",
      "body": "Sarah Chen (chpt_03AZ) is now paused. Reason: Personal leave.",
      "read": false,
      "created_at": "2026-03-26T09:15:30Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 12
  }
}

GET /api/v1/notifications/api/v1/notifications/:id

Get a single notification

Public

Response Example

{
  "notification_id": "notif_7GH2MX1PQ",
  "recipient_id": "user_coord_99XZ",
  "type": "mentor_status_change",
  "title": "Mentor Sarah Chen has been paused",
  "body": "Sarah Chen (chpt_03AZ) is now paused. Reason: Personal leave.",
  "payload": {
    "mentor_id": "mntr_01HX4V2K8P",
    "new_status": "paused",
    "reason": "Personal leave",
    "deep_link": "/mentors/mntr_01HX4V2K8P"
  },
  "read": false,
  "created_at": "2026-03-26T09:15:30Z"
}

POST /api/v1/notifications/api/v1/notifications

Create and dispatch a notification to one or more recipients

Public

Request Example

{
  "recipient_ids": [
    "user_coord_99XZ",
    "user_coord_11AB"
  ],
  "type": "mentor_status_change",
  "title": "Mentor paused",
  "body": "James Okafor has been paused due to expired certification.",
  "payload": {
    "mentor_id": "mntr_02BY7M3RL",
    "new_status": "paused",
    "reason": "Certification expired",
    "deep_link": "/mentors/mntr_02BY7M3RL"
  }
}

Response Example

{
  "notification_id": "notif_8KL3NY2RS",
  "recipient_ids": [
    "user_coord_99XZ",
    "user_coord_11AB"
  ],
  "type": "mentor_status_change",
  "title": "Mentor paused",
  "dispatched_at": "2026-03-26T10:00:00Z",
  "created_at": "2026-03-26T10:00:00Z"
}

PUT /api/v1/notifications/api/v1/notifications/:id

Update a notification (e.g. mark as read)

Public

Request Example

{
  "read": true
}

Response Example

{
  "notification_id": "notif_7GH2MX1PQ",
  "read": true,
  "updated_at": "2026-03-26T10:05:00Z"
}

DELETE /api/v1/notifications/api/v1/notifications/:id

Delete a notification record

Public

Response Example

{
  "notification_id": "notif_7GH2MX1PQ",
  "deleted": true,
  "deleted_at": "2026-03-26T10:10:00Z"
}

POST /api/v1/notifications/api/v1/notifications/push

Send push notification to a list of recipients

Public

Request Example

{
  "recipient_ids": [
    "user_coord_99XZ",
    "user_coord_11AB"
  ],
  "title": "Mentor Status Update",
  "body": "Sarah Chen is now active and available for assignments."
}

Response Example

{
  "sent_count": 2,
  "failed_count": 0,
  "sent_to": [
    "user_coord_99XZ",
    "user_coord_11AB"
  ],
  "dispatched_at": "2026-03-26T09:20:10Z"
}

POST /api/v1/notifications/api/v1/notifications/in-app

Send in-app notification with structured payload

Public

Request Example

{
  "recipient_ids": [
    "user_coord_99XZ"
  ],
  "payload": {
    "type": "mentor_status_change",
    "mentor_id": "mntr_01HX4V2K8P",
    "new_status": "active",
    "reason": null,
    "deep_link": "/mentors/mntr_01HX4V2K8P"
  }
}

Response Example

{
  "sent_count": 1,
  "failed_count": 0,
  "dispatched_at": "2026-03-26T09:20:15Z"
}

GET /api/v1/notifications/api/v1/mentors/:mentor_id/coordinators

List coordinators responsible for a given mentor

Public

Response Example

{
  "data": [
    {
      "coordinator_id": "user_coord_99XZ",
      "full_name": "Lena Fischer",
      "email": "lena.fischer@example.org",
      "chapter_id": "chpt_03AZ"
    }
  ],
  "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"
}