Certification Repository - API Contract

GET /api/v1/certification-records/api/v1/certification-records

List all raw certification records from the repository

Public

Response Example

{
  "data": [
    {
      "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_history": [
        {
          "renewed_at": "2026-03-01T00:00:00Z",
          "expires_at": "2027-03-01T00:00:00Z"
        }
      ],
      "updated_at": "2026-03-01T08:14:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 124
  }
}

GET /api/v1/certification-records/api/v1/certification-records/:mentorId

Get certification record for a mentor (maps to getCertification)

Public

Response Example

{
  "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_history": [
    {
      "renewed_at": "2025-09-01T00:00:00Z",
      "expires_at": "2026-03-01T00:00:00Z"
    },
    {
      "renewed_at": "2026-03-01T00:00:00Z",
      "expires_at": "2027-03-01T00:00:00Z"
    }
  ],
  "updated_at": "2026-03-01T08:14:00Z"
}

POST /api/v1/certification-records/api/v1/certification-records

Create or upsert a certification record (maps to upsertCertification)

Public

Request Example

{
  "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"
}

Response Example

{
  "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_history": [],
  "upserted": true,
  "updated_at": "2026-03-26T10:00:00Z"
}

PUT /api/v1/certification-records/api/v1/certification-records/:mentorId

Update a certification record in full

Public

Request Example

{
  "cert_type": "peer_mentor_level_2",
  "status": "expired",
  "expires_at": "2026-03-25T00:00:00Z"
}

Response Example

{
  "mentor_id": "mentor-42",
  "cert_type": "peer_mentor_level_2",
  "status": "expired",
  "expires_at": "2026-03-25T00:00:00Z",
  "updated_at": "2026-03-26T10:00:00Z"
}

DELETE /api/v1/certification-records/api/v1/certification-records/:mentorId

Delete a certification record

Public

Response Example

{
  "deleted": true,
  "mentor_id": "mentor-42"
}

POST /api/v1/certification-records/api/v1/certification-records/:mentorId/renewals

Append a new renewal entry to a mentor's renewal history (maps to appendRenewalHistory)

Public

Request Example

{
  "renewed_at": "2026-03-26T00:00:00Z",
  "expires_at": "2027-03-26T00:00:00Z"
}

Response Example

{
  "mentor_id": "mentor-42",
  "renewal_appended": true,
  "renewal_entry": {
    "renewed_at": "2026-03-26T00:00:00Z",
    "expires_at": "2027-03-26T00:00:00Z"
  },
  "total_renewals": 3,
  "updated_at": "2026-03-26T10:00:00Z"
}

GET /api/v1/certification-records/api/v1/certification-records/expiring

Get certification records expiring within N days (maps to getExpiringCertifications)

Public

Response Example

{
  "data": [
    {
      "mentor_id": "mentor-19",
      "cert_type": "peer_mentor_level_1",
      "status": "active",
      "issued_at": "2025-04-10T00:00:00Z",
      "expires_at": "2026-04-10T00:00:00Z",
      "days_until_expiry": 15
    }
  ],
  "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"
}