{
    "openapi": "3.0.3",
    "info": {
        "title": "KBN World Federation partner API",
        "version": "1.1.0",
        "description": "Read-only access to the official KBN world ranking, fighter profiles, events, verified results and document verification.\n\nNo endpoint exposes identity or contact data, and nothing sent to the API can create or change ranking points: points are earned only through verified sporting performance.\n\nWebhooks: ranking.published, result.verified, licence.suspended, licence.issued, event.sanctioned. Each delivery carries X-KBN-Event, X-KBN-Delivery, X-KBN-Timestamp, X-KBN-Attempt, X-KBN-Signature (HMAC-SHA256 of the body) and X-KBN-Signature-Timestamped (HMAC-SHA256 of \"{timestamp}.{body}\"); replays add X-KBN-Replay-Of.",
        "contact": {
            "email": "holdingkbn@gmail.com"
        }
    },
    "servers": [
        {
            "url": "https://kbn.hbzgroup.co.uk/api/v1"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/rankings": {
            "get": {
                "operationId": "getRankings",
                "summary": "One division ranking table",
                "description": "Required scope: `rankings.read`.",
                "tags": [
                    "Rankings"
                ],
                "parameters": [
                    {
                        "name": "disc",
                        "in": "query",
                        "description": "kickboxing, mma, boxing, muay-thai",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "cat",
                        "in": "query",
                        "description": "pro or am",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "g",
                        "in": "query",
                        "description": "m or f",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "wc",
                        "in": "query",
                        "description": "weight class slug, e.g. welterweight",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "scope",
                        "in": "query",
                        "description": "world, a continent name or a country slug",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "as_of": {
                                            "type": "string",
                                            "format": "date"
                                        },
                                        "division": {
                                            "$ref": "#/components/schemas/Division"
                                        },
                                        "scope": {
                                            "type": "string"
                                        },
                                        "count": {
                                            "type": "integer"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/RankedRow"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/divisions": {
            "get": {
                "operationId": "listDivisions",
                "summary": "Divisions with ranked fighters and their world leader",
                "description": "Required scope: `rankings.read`.",
                "tags": [
                    "Rankings"
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "as_of": {
                                            "type": "string"
                                        },
                                        "count": {
                                            "type": "integer"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/DivisionSummary"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/fighters": {
            "get": {
                "operationId": "listFighters",
                "summary": "Fighter directory",
                "description": "Required scope: `fighters.read`.",
                "tags": [
                    "Fighters"
                ],
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "name search",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "country slug",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "disc",
                        "in": "query",
                        "description": "discipline",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "description": "licensed, applicant, suspended",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "as_of": {
                                            "type": "string",
                                            "format": "date"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/Meta"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Fighter"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/fighters/{slug}": {
            "get": {
                "operationId": "getFighter",
                "summary": "Fighter profile with verified bouts and ranks",
                "description": "Minors return name, country and division only. Required scope: `fighters.read`.",
                "tags": [
                    "Fighters"
                ],
                "parameters": [
                    {
                        "name": "slug",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "as_of": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/Fighter"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/events": {
            "get": {
                "operationId": "listEvents",
                "summary": "Sanctioned events",
                "description": "Required scope: `events.read`.",
                "tags": [
                    "Events"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "description": "country slug",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "level",
                        "in": "query",
                        "description": "national, international, continental, worldcup, world",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "upcoming",
                        "in": "query",
                        "description": "1 for upcoming only",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "as_of": {
                                            "type": "string",
                                            "format": "date"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/Meta"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Event"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/events/{code}": {
            "get": {
                "operationId": "getEvent",
                "summary": "One sanctioned event",
                "description": "Required scope: `events.read`.",
                "tags": [
                    "Events"
                ],
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "as_of": {
                                            "type": "string"
                                        },
                                        "data": {
                                            "$ref": "#/components/schemas/Event"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/events/{code}/results": {
            "get": {
                "operationId": "getEventResults",
                "summary": "Verified results of one event",
                "description": "Required scope: `results.read`.",
                "tags": [
                    "Results"
                ],
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "event": {
                                            "$ref": "#/components/schemas/Event"
                                        },
                                        "count": {
                                            "type": "integer"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Result"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/results": {
            "get": {
                "operationId": "listResults",
                "summary": "Verified results across all events",
                "description": "Newest events first. Results of minors are never included. Required scope: `results.read`.",
                "tags": [
                    "Results"
                ],
                "parameters": [
                    {
                        "name": "since",
                        "in": "query",
                        "description": "YYYY-MM-DD",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "description": "fighter country slug",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "disc",
                        "in": "query",
                        "description": "discipline",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "event",
                        "in": "query",
                        "description": "event code",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "as_of": {
                                            "type": "string",
                                            "format": "date"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/Meta"
                                        },
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Result"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/verify/{number}": {
            "get": {
                "operationId": "verifyDocument",
                "summary": "Verify a licence no., certificate no. or KBN Fighter ID",
                "description": "Required scope: `any`.",
                "tags": [
                    "Account"
                ],
                "parameters": [
                    {
                        "name": "number",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "valid": {
                                            "type": "boolean"
                                        },
                                        "status": {
                                            "type": "string",
                                            "enum": [
                                                "ACTIVE",
                                                "SUSPENDED",
                                                "EXPIRED",
                                                "PENDING VERIFICATION",
                                                "NO MATCHING RECORD"
                                            ]
                                        },
                                        "matched": {
                                            "type": "string"
                                        },
                                        "fighter": {
                                            "$ref": "#/components/schemas/FighterSummary"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/me": {
            "get": {
                "operationId": "getMe",
                "summary": "The calling API key: partner, scopes, limits, expiry and usage",
                "description": "Required scope: `any`.",
                "tags": [
                    "Account"
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "name": {
                                                    "type": "string"
                                                },
                                                "partner": {
                                                    "type": "object",
                                                    "nullable": true
                                                },
                                                "scopes": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string",
                                                        "enum": [
                                                            "rankings.read",
                                                            "fighters.read",
                                                            "events.read",
                                                            "results.read"
                                                        ]
                                                    }
                                                },
                                                "rate_limit_per_minute": {
                                                    "type": "integer"
                                                },
                                                "expires_at": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "request_count": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthenticated"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "API key issued by KBN World HQ (Authorization: Bearer kbn_…). X-API-Key is also accepted."
            }
        },
        "responses": {
            "Unauthenticated": {
                "description": "Missing, unknown, revoked, expired or disabled key",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "Forbidden": {
                "description": "The key lacks the required scope (insufficient_scope)",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "RateLimited": {
                "description": "Per-key rate limit exceeded; see Retry-After",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string"
                    }
                }
            },
            "Meta": {
                "type": "object",
                "properties": {
                    "page": {
                        "type": "integer"
                    },
                    "per_page": {
                        "type": "integer"
                    },
                    "total": {
                        "type": "integer"
                    },
                    "last_page": {
                        "type": "integer"
                    }
                }
            },
            "Division": {
                "type": "object",
                "properties": {
                    "discipline": {
                        "type": "string"
                    },
                    "category": {
                        "type": "string"
                    },
                    "gender": {
                        "type": "string"
                    },
                    "weight_class": {
                        "type": "string"
                    },
                    "label": {
                        "type": "string"
                    }
                }
            },
            "DivisionSummary": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/Division"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "ranked": {
                                "type": "integer"
                            },
                            "query": {
                                "type": "object"
                            },
                            "leader": {
                                "type": "object",
                                "properties": {
                                    "points": {
                                        "type": "number"
                                    },
                                    "fighter": {
                                        "$ref": "#/components/schemas/FighterSummary"
                                    }
                                }
                            }
                        }
                    }
                ]
            },
            "FighterSummary": {
                "type": "object",
                "properties": {
                    "slug": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "nickname": {
                        "type": "string",
                        "nullable": true
                    },
                    "country": {
                        "type": "object"
                    },
                    "division": {
                        "$ref": "#/components/schemas/Division"
                    },
                    "status": {
                        "type": "string"
                    },
                    "ranking_published": {
                        "type": "boolean"
                    },
                    "licence_status": {
                        "type": "string"
                    },
                    "fighter_code": {
                        "type": "string",
                        "nullable": true
                    }
                }
            },
            "Fighter": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/FighterSummary"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "points": {
                                "type": "number",
                                "nullable": true
                            },
                            "record": {
                                "type": "object"
                            },
                            "ranks": {
                                "type": "object",
                                "nullable": true
                            }
                        }
                    }
                ]
            },
            "RankedRow": {
                "type": "object",
                "properties": {
                    "rank": {
                        "type": "integer"
                    },
                    "movement": {
                        "type": "integer",
                        "nullable": true,
                        "description": "null = new entry"
                    },
                    "points": {
                        "type": "number"
                    },
                    "record": {
                        "type": "object"
                    },
                    "fighter": {
                        "$ref": "#/components/schemas/FighterSummary"
                    }
                }
            },
            "Event": {
                "type": "object",
                "properties": {
                    "code": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "city": {
                        "type": "string",
                        "nullable": true
                    },
                    "country": {
                        "type": "string"
                    },
                    "date": {
                        "type": "string",
                        "format": "date"
                    },
                    "level": {
                        "type": "string",
                        "nullable": true
                    },
                    "multiplier": {
                        "type": "number"
                    },
                    "is_live": {
                        "type": "boolean"
                    },
                    "status": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string"
                    }
                }
            },
            "Result": {
                "type": "object",
                "properties": {
                    "event": {
                        "$ref": "#/components/schemas/Event"
                    },
                    "fighter": {
                        "$ref": "#/components/schemas/FighterSummary"
                    },
                    "opponent": {
                        "type": "string"
                    },
                    "result": {
                        "type": "string",
                        "enum": [
                            "W",
                            "L",
                            "D",
                            "NC"
                        ]
                    },
                    "method": {
                        "type": "string",
                        "nullable": true
                    },
                    "round": {
                        "type": "integer",
                        "nullable": true
                    },
                    "points": {
                        "type": "object",
                        "properties": {
                            "base": {
                                "type": "number"
                            },
                            "multiplier": {
                                "type": "number"
                            },
                            "time_value": {
                                "type": "number"
                            },
                            "total": {
                                "type": "number"
                            }
                        }
                    }
                }
            }
        }
    }
}