Badge Repository - API Contract

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

Query earned badges for a peer mentor (internal data access — proxied via badge-award-service)

Auth Required system

Response Example

{
  "data": [
    {
      "id": "earned-001",
      "badge_definition_id": "bdg-def-001",
      "peer_mentor_id": "pm-kari-001",
      "awarded_at": "2026-01-22T14:35:00Z",
      "awarded_by": "system",
      "revoked_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /api/v1/earned-badges/api/v1/earned-badges/by-organisation

Query all earned badges within an organisation

Auth Required systemadmin

Response Example

{
  "data": [
    {
      "id": "earned-001",
      "badge_definition_id": "bdg-def-001",
      "peer_mentor_id": "pm-kari-001",
      "awarded_at": "2026-01-22T14:35:00Z",
      "revoked_at": null
    },
    {
      "id": "earned-003",
      "badge_definition_id": "bdg-def-001",
      "peer_mentor_id": "pm-lars-002",
      "awarded_at": "2026-01-28T09:10:00Z",
      "revoked_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 89
  }
}

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

Persist a new earned badge record

Auth Required system

Request Example

{
  "badge_definition_id": "bdg-def-004",
  "peer_mentor_id": "pm-kari-001",
  "awarded_at": "2026-03-26T16:00:12Z",
  "awarded_by": "system"
}

Response Example

{
  "id": "earned-017",
  "badge_definition_id": "bdg-def-004",
  "peer_mentor_id": "pm-kari-001",
  "awarded_at": "2026-03-26T16:00:12Z",
  "awarded_by": "system",
  "revoked_at": null
}

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

Check if an earned badge record exists for a peer mentor and definition

Auth Required system

Response Example

{
  "exists": true,
  "earned_badge_id": "earned-001"
}

Additional Metadata

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