Certification Management Service - API Contract

GET /api/v1/certifications/api/v1/certifications

List all mentor certifications with optional filtering

Public

Response Example

{
  "data": [
    {
      "id": "cert-001",
      "mentor_id": "mentor-42",
      "cert_type": "peer_mentor_level_2",
      "status": "active",
      "issued_at": "2025-09-01T00:00:00Z",
      "expires_at": "2026-09-01T00:00:00Z",
      "renewal_count": 1,
      "created_at": "2025-09-01T08:14:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 87
  }
}

GET /api/v1/certifications/api/v1/certifications/:id

Get a single certification record by ID

Public

Response Example

{
  "id": "cert-001",
  "mentor_id": "mentor-42",
  "cert_type": "peer_mentor_level_2",
  "status": "active",
  "issued_at": "2025-09-01T00:00:00Z",
  "expires_at": "2026-09-01T00:00:00Z",
  "renewal_count": 1,
  "renewal_history": [
    {
      "renewed_at": "2025-09-01T08:14:00Z",
      "expires_at": "2026-09-01T00:00:00Z"
    }
  ],
  "created_at": "2025-09-01T08:14:00Z",
  "updated_at": "2025-09-01T08:14:00Z"
}

POST /api/v1/certifications/api/v1/certifications

Create a new certification for a mentor

Public

Request Example

{
  "mentor_id": "mentor-42",
  "cert_type": "peer_mentor_level_2",
  "issued_at": "2026-03-01T00:00:00Z",
  "expires_at": "2027-03-01T00:00:00Z"
}

Response Example

{
  "id": "cert-002",
  "mentor_id": "mentor-42",
  "cert_type": "peer_mentor_level_2",
  "status": "active",
  "issued_at": "2026-03-01T00:00:00Z",
  "expires_at": "2027-03-01T00:00:00Z",
  "renewal_count": 0,
  "created_at": "2026-03-26T10:00:00Z"
}

PUT /api/v1/certifications/api/v1/certifications/:id

Record a certification renewal or update certification details

Public

Request Example

{
  "issued_at": "2026-03-26T00:00:00Z",
  "expires_at": "2027-03-26T00:00:00Z",
  "cert_type": "peer_mentor_level_2"
}

Response Example

{
  "id": "cert-001",
  "mentor_id": "mentor-42",
  "cert_type": "peer_mentor_level_2",
  "status": "active",
  "issued_at": "2026-03-26T00:00:00Z",
  "expires_at": "2027-03-26T00:00:00Z",
  "renewal_count": 2,
  "updated_at": "2026-03-26T10:05:00Z"
}

DELETE /api/v1/certifications/api/v1/certifications/:id

Remove a certification record

Public

Response Example

{
  "deleted": true,
  "id": "cert-001"
}

GET /api/v1/certifications/api/v1/certifications/:id/status

Get the current certification status for a mentor (maps to getCertificationStatus)

Public

Response Example

{
  "mentor_id": "mentor-42",
  "status": "active",
  "cert_type": "peer_mentor_level_2",
  "expires_at": "2027-03-26T00:00:00Z",
  "days_until_expiry": 365,
  "is_expiring_soon": false
}

GET /api/v1/certifications/api/v1/certifications/expiring

Get all certifications expiring within N days (maps to getExpiringCertifications)

Public

Response Example

{
  "data": [
    {
      "id": "cert-007",
      "mentor_id": "mentor-19",
      "mentor_name": "Lars Eriksen",
      "cert_type": "peer_mentor_level_1",
      "expires_at": "2026-04-10T00:00:00Z",
      "days_until_expiry": 15,
      "status": "active"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3
  }
}

Additional Metadata

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