Badge Award Service - API Contract

GET /api/v1/earned-badges/api/v1/earned-badges

List earned badges, filterable by peer mentor or organisation

Auth Required admincoordinatorpeer_mentor

Response Example

{
  "data": [
    {
      "id": "earned-001",
      "badge_definition_id": "bdg-def-001",
      "peer_mentor_id": "pm-kari-001",
      "badge_name": "First Session",
      "icon_url": "https://assets.example.com/badges/first-session.svg",
      "awarded_at": "2026-01-22T14:35:00Z",
      "awarded_by": "system"
    },
    {
      "id": "earned-002",
      "badge_definition_id": "bdg-def-002",
      "peer_mentor_id": "pm-kari-001",
      "badge_name": "Streak Champion",
      "icon_url": "https://assets.example.com/badges/streak-champion.svg",
      "awarded_at": "2026-02-21T00:01:00Z",
      "awarded_by": "system"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

GET /api/v1/earned-badges/api/v1/earned-badges/:id

Get a specific earned badge record

Auth Required admincoordinatorpeer_mentor

Response Example

{
  "id": "earned-002",
  "badge_definition_id": "bdg-def-002",
  "peer_mentor_id": "pm-kari-001",
  "organisation_id": "org-nhf-oslo",
  "badge_name": "Streak Champion",
  "badge_description": "Maintained an active mentoring streak for 30 consecutive days",
  "icon_url": "https://assets.example.com/badges/streak-champion.svg",
  "awarded_at": "2026-02-21T00:01:00Z",
  "awarded_by": "system",
  "revoked_at": null,
  "revoke_reason": null
}

POST /api/v1/earned-badges/api/v1/earned-badges

Award a badge to a peer mentor (manual award or system-triggered)

Auth Required adminsystem

Request Example

{
  "badge_definition_id": "bdg-def-003",
  "peer_mentor_id": "pm-kari-001",
  "awarded_by": "admin-per-001",
  "note": "Manual award for outstanding contribution at the February retreat"
}

Response Example

{
  "id": "earned-015",
  "badge_definition_id": "bdg-def-003",
  "peer_mentor_id": "pm-kari-001",
  "organisation_id": "org-nhf-oslo",
  "badge_name": "Community Builder",
  "badge_description": "Recognised for exceptional contribution to the peer mentor community",
  "icon_url": "https://assets.example.com/badges/community-builder.svg",
  "awarded_at": "2026-03-26T11:45:00Z",
  "awarded_by": "admin-per-001",
  "note": "Manual award for outstanding contribution at the February retreat"
}

DELETE /api/v1/earned-badges/api/v1/earned-badges/:id

Revoke an earned badge if criteria are no longer met or by admin action

Auth Required adminsystem

Request Example

{
  "revoke_reason": "Criteria no longer met — activity count dropped below threshold"
}

Response Example

{
  "id": "earned-002",
  "revoked": true,
  "revoked_at": "2026-03-26T12:00:00Z",
  "revoke_reason": "Criteria no longer met — activity count dropped below threshold"
}

GET /api/v1/earned-badges/api/v1/earned-badges/check

Check whether a specific peer mentor has earned a given badge

Auth Required admincoordinatorpeer_mentorsystem

Response Example

{
  "badge_definition_id": "bdg-def-002",
  "peer_mentor_id": "pm-kari-001",
  "has_earned": true,
  "earned_badge_id": "earned-002",
  "awarded_at": "2026-02-21T00:01:00Z"
}

Additional Metadata

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