Recognition Tier Service - API Contract

GET /api/v1/recognition-tiers/api/v1/recognition-tiers

List all available recognition tiers for an organisation

Auth Required admincoordinatorpeer_mentor

Response Example

{
  "data": [
    {
      "id": "tier-bronze",
      "organisation_id": "org-nhf-oslo",
      "name": "Bronze Mentor",
      "description": "Entry-level recognition for active peer mentors",
      "level": 1,
      "color": "#CD7F32",
      "icon_url": "https://assets.example.com/tiers/bronze.svg",
      "min_badges_required": 2,
      "is_active": true
    },
    {
      "id": "tier-silver",
      "organisation_id": "org-nhf-oslo",
      "name": "Silver Mentor",
      "description": "Experienced peer mentor with sustained engagement",
      "level": 2,
      "color": "#C0C0C0",
      "icon_url": "https://assets.example.com/tiers/silver.svg",
      "min_badges_required": 5,
      "is_active": true
    },
    {
      "id": "tier-gold",
      "organisation_id": "org-nhf-oslo",
      "name": "Gold Mentor",
      "description": "Elite peer mentor — top contributor in the organisation",
      "level": 3,
      "color": "#FFD700",
      "icon_url": "https://assets.example.com/tiers/gold.svg",
      "min_badges_required": 8,
      "is_active": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3
  }
}

GET /api/v1/recognition-tiers/api/v1/recognition-tiers/:id

Get a specific recognition tier definition

Auth Required admincoordinatorpeer_mentor

Response Example

{
  "id": "tier-gold",
  "organisation_id": "org-nhf-oslo",
  "name": "Gold Mentor",
  "description": "Elite peer mentor — top contributor in the organisation",
  "level": 3,
  "color": "#FFD700",
  "icon_url": "https://assets.example.com/tiers/gold.svg",
  "min_badges_required": 8,
  "is_active": true,
  "current_holders": 12
}

POST /api/v1/recognition-tiers/api/v1/recognition-tier-assignments

Assign a recognition tier to a user

Auth Required adminsystem

Request Example

{
  "tier_id": "tier-silver",
  "user_id": "pm-kari-001",
  "awarded_at": "2026-03-26T14:30:00Z",
  "awarded_by": "system",
  "note": "Automatically assigned after earning 5 badges"
}

Response Example

{
  "id": "tier-assign-041",
  "tier_id": "tier-silver",
  "user_id": "pm-kari-001",
  "tier_name": "Silver Mentor",
  "awarded_at": "2026-03-26T14:30:00Z",
  "awarded_by": "system",
  "note": "Automatically assigned after earning 5 badges",
  "is_active": true
}

DELETE /api/v1/recognition-tiers/api/v1/recognition-tier-assignments/:id

Revoke an active recognition tier assignment

Auth Required adminsystem

Request Example

{
  "revoke_reason": "Tier re-evaluated — badge count no longer meets Silver threshold"
}

Response Example

{
  "id": "tier-assign-041",
  "revoked": true,
  "revoked_at": "2026-03-26T15:00:00Z",
  "revoke_reason": "Tier re-evaluated — badge count no longer meets Silver threshold"
}

GET /api/v1/recognition-tiers/api/v1/recognition-tier-assignments/active

Get the currently active recognition tier assignment for a user

Auth Required admincoordinatorpeer_mentor

Response Example

{
  "assignment_id": "tier-assign-041",
  "user_id": "pm-kari-001",
  "tier": {
    "id": "tier-silver",
    "name": "Silver Mentor",
    "level": 2,
    "color": "#C0C0C0",
    "icon_url": "https://assets.example.com/tiers/silver.svg"
  },
  "awarded_at": "2026-03-26T14:30:00Z",
  "is_active": true
}

Additional Metadata

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