KBN public API v1

Authentication

Every request carries an API key as a Bearer token. Keys are issued by KBN World HQ, stored only as SHA-256 hashes and carry scopes:

curl -H "Authorization: Bearer kbn_xxxxxxxx_…" \
  "https://kbn.hbzgroup.co.uk/api/v1/rankings?disc=kickboxing&cat=pro&g=m&wc=welterweight&scope=world"

Rate limits

Each key has its own per-minute limit (default 60). Responses include X-RateLimit-Limit and X-RateLimit-Remaining; exceeding the limit returns 429 with Retry-After. Every response also carries as_of, the date the ranking was computed for.

GET /api/v1/rankings rankings.read

One division table. Query: disc (kickboxing, mma, boxing, muay-thai), cat (pro, am), g (m, f), wc (weight class slug, e.g. welterweight), scope (world, a continent name, or a country slug).

{
  "as_of": "2026-09-28",
  "division": {"discipline": "Kickboxing", "category": "Professional", "gender": "M", "weight_class": "Welterweight", "label": "Professional · Men's Kickboxing · Welterweight"},
  "scope": "world", "count": 6,
  "data": [
    {"rank": 1, "movement": 0, "points": 635.0, "record": {"W": 4, "L": 0, "D": 0, "NC": 0, "KO": 1},
     "fighter": {"slug": "karimov", "name": "Aleksei Karimov", "country": {"slug": "uzbekistan", "name": "Uzbekistan", "flag": "🇺🇿", "continent": "Asia"},
                 "division": {…}, "status": "licensed", "licence_status": "ACTIVE", "fighter_code": "KBN-UZ-1040"}}
  ]
}

GET /api/v1/fighters fighters.read

Paginated directory (q, country, disc, status, per_page ≤ 100). GET /api/v1/fighters/{slug} returns the profile: points, verified record, world/continental/national ranks, licence identifiers and status, verified bouts with the base × multiplier × time-value breakdown, and the 12-month points history. Minors (under 18) return only name, country and division.

curl -H "Authorization: Bearer …" https://kbn.hbzgroup.co.uk/api/v1/fighters/karimov

GET /api/v1/events events.read · GET /api/v1/events/{code}/results results.read

Sanctioned events (filters: country, level, upcoming=1) with their level and effective multiplier. The results endpoint lists verified results only, each with its point breakdown. Pending or rejected results are never exposed.

GET /api/v1/verify/{number} any key

Checks a licence number, certificate number or Fighter ID against the register. Returns valid, the licence status (ACTIVE / SUSPENDED / EXPIRED / PENDING VERIFICATION), identifiers, ranks and the verified record — the same authority as worldkbn.com/verify. Unknown numbers return 404.

Webhooks

Register an HTTPS endpoint in the admin and choose events:

• ranking.published — A fighter's ranking is published
• result.verified — A bout result is verified
• licence.suspended — A licence is suspended

Each delivery is a JSON POST with headers X-KBN-Event, X-KBN-Delivery and X-KBN-Signature: sha256=<HMAC-SHA256 of the raw body with your secret>. Verify the signature before trusting the payload; failed deliveries can be retried from the admin log.

{
  "id": "5e0c…", "event": "ranking.published", "created_at": "2026-09-28T00:00:00+01:00",
  "data": {"fighter": {"slug": "reid", "name": "Callum Reid", "country": "uk", "fighter_code": "KBN-GB-1041", "licence_no": "KBN-L-26-40101", "certificate_no": "KBN-WR-26-100201"},
           "division": {…}, "status": "licensed", "licence_status": "ACTIVE", "url": "https://kbn.hbzgroup.co.uk/fighters/reid"}
}

# Node.js verification
const sig = 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
if (sig !== req.headers['x-kbn-signature']) return res.status(401).end();

Errors

The API is read-only. Nothing you send can create, edit or adjust points or verification statuses; those change only through KBN's admin workflow.