Badge Configuration Service

List all badge definitions for an organisation

{
  "data": [
    {
      "id": "bdg-def-001",
      "organisation_id": "org-nhf-oslo",
      "name": "First Session",
      "description": "Awarded after completing your first peer mentoring session",
      "icon_url": "https://assets.example.com/badges/first-session.svg",
      "criteria": {
        "type": "session_count",
        "threshold": 1
      },
      "category": "milestone",
      "is_active": true,
      "created_at": "2026-01-10T08:00:00Z",
      "updated_at": "2026-01-10T08:00:00Z"
    },
    {
      "id": "bdg-def-002",
      "organisation_id": "org-nhf-oslo",
      "name": "Streak Champion",
      "description": "Maintained an active mentoring streak for 30 consecutive days",
      "icon_url": "https://assets.example.com/badges/streak-champion.svg",
      "criteria": {
        "type": "streak_days",
        "threshold": 30
      },
      "category": "engagement",
      "is_active": true,
      "created_at": "2026-01-10T08:05:00Z",
      "updated_at": "2026-02-01T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8
  }
}

Get a single badge definition by ID

{
  "id": "bdg-def-002",
  "organisation_id": "org-nhf-oslo",
  "name": "Streak Champion",
  "description": "Maintained an active mentoring streak for 30 consecutive days",
  "icon_url": "https://assets.example.com/badges/streak-champion.svg",
  "locked_icon_url": "https://assets.example.com/badges/streak-champion-locked.svg",
  "criteria": {
    "type": "streak_days",
    "threshold": 30
  },
  "category": "engagement",
  "is_active": true,
  "earned_count": 47,
  "created_at": "2026-01-10T08:05:00Z",
  "updated_at": "2026-02-01T14:00:00Z"
}

Create a new badge definition for an organisation

{
  "organisation_id": "org-nhf-oslo",
  "name": "Training Master",
  "description": "Completed 10 or more training modules",
  "icon_url": "https://assets.example.com/badges/training-master.svg",
  "locked_icon_url": "https://assets.example.com/badges/training-master-locked.svg",
  "criteria": {
    "type": "training_completion_count",
    "threshold": 10
  },
  "category": "learning",
  "is_active": true
}

{
  "id": "bdg-def-009",
  "organisation_id": "org-nhf-oslo",
  "name": "Training Master",
  "description": "Completed 10 or more training modules",
  "icon_url": "https://assets.example.com/badges/training-master.svg",
  "locked_icon_url": "https://assets.example.com/badges/training-master-locked.svg",
  "criteria": {
    "type": "training_completion_count",
    "threshold": 10
  },
  "category": "learning",
  "is_active": true,
  "earned_count": 0,
  "created_at": "2026-03-26T11:30:00Z",
  "updated_at": "2026-03-26T11:30:00Z"
}

Update an existing badge definition

{
  "name": "Training Master",
  "description": "Completed 10 or more approved training modules",
  "criteria": {
    "type": "training_completion_count",
    "threshold": 10
  },
  "is_active": true
}

{
  "id": "bdg-def-009",
  "organisation_id": "org-nhf-oslo",
  "name": "Training Master",
  "description": "Completed 10 or more approved training modules",
  "icon_url": "https://assets.example.com/badges/training-master.svg",
  "locked_icon_url": "https://assets.example.com/badges/training-master-locked.svg",
  "criteria": {
    "type": "training_completion_count",
    "threshold": 10
  },
  "category": "learning",
  "is_active": true,
  "earned_count": 0,
  "created_at": "2026-03-26T11:30:00Z",
  "updated_at": "2026-03-26T12:00:00Z"
}

Soft-delete a badge definition (deactivates it, preserves earned records)

{
  "id": "bdg-def-009",
  "deleted": true,
  "deleted_at": "2026-03-26T13:00:00Z"
}

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