Badge Definition Repository - API Contract

GET /api/v1/badge-definitions/api/v1/badge-definitions

Query all badge definitions for an organisation (internal — proxied via badge-configuration-service)

Auth Required system

Response Example

{
  "data": [
    {
      "id": "bdg-def-001",
      "organisation_id": "org-nhf-oslo",
      "name": "First Session",
      "criteria": {
        "type": "session_count",
        "threshold": 1
      },
      "is_active": true,
      "created_at": "2026-01-10T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8
  }
}

GET /api/v1/badge-definitions/api/v1/badge-definitions/:id

Fetch a single badge definition by ID

Auth Required system

Response Example

{
  "id": "bdg-def-002",
  "organisation_id": "org-nhf-oslo",
  "name": "Streak Champion",
  "description": "Maintained an active mentoring streak for 30 consecutive days",
  "criteria": {
    "type": "streak_days",
    "threshold": 30
  },
  "is_active": true,
  "created_at": "2026-01-10T08:05:00Z",
  "updated_at": "2026-02-01T14:00:00Z"
}

POST /api/v1/badge-definitions/api/v1/badge-definitions

Persist a new badge definition

Auth Required system

Request Example

{
  "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",
  "criteria": {
    "type": "training_completion_count",
    "threshold": 10
  },
  "category": "learning",
  "is_active": true
}

Response Example

{
  "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",
  "criteria": {
    "type": "training_completion_count",
    "threshold": 10
  },
  "category": "learning",
  "is_active": true,
  "created_at": "2026-03-26T11:30:00Z",
  "updated_at": "2026-03-26T11:30:00Z"
}

PUT /api/v1/badge-definitions/api/v1/badge-definitions/:id

Update an existing badge definition record

Auth Required system

Request Example

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

Response Example

{
  "id": "bdg-def-009",
  "organisation_id": "org-nhf-oslo",
  "name": "Training Master",
  "description": "Completed 10 or more approved training modules",
  "criteria": {
    "type": "training_completion_count",
    "threshold": 10
  },
  "is_active": true,
  "updated_at": "2026-03-26T12:00:00Z"
}

Additional Metadata

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