{ "openapi": "3.1.0", "info": { "title": "Cito UFC API", "version": "1.0.0", "summary": "UFC and MMA fight data: fighters, cards, round stats, rankings, odds and live state.", "description": "Self-serve UFC data API for developers. Fighters, event cards, bout and round-by-round\nstatistics, divisional rankings, betting odds and live fight-night state.\n\n**Authentication** — send your key in the `x-api-key` header.\n\n**Getting a key** — free tier of 500 calls/month, no credit card:\nhttps://citoapi.com/signup/\n\n**Conventions** — responses are wrapped in a `{ data, meta }` envelope. Paginated\nlists carry `meta.page`, `meta.totalPages` and `meta.hasNextPage`. Timestamps are\nISO-8601 UTC. Errors are `{ error: { code, message, request_id } }`.\n\n**Odds** — an empty `data.markets` array is a normal coverage state for third-party\nmarket data, not an error. Odds are for research, media and display.\n\n**Live** — in-round state is available over REST polling and over WebSocket at\n`wss://api.citoapi.com/api/v1/ufc/live/ws`. See https://citoapi.com/docs/api/ufc/\n\n**Disclaimer** — independent API, not affiliated with, endorsed by or licensed by\nthe UFC, Zuffa, TKO Group Holdings or any promotion.", "contact": { "name": "Cito API", "url": "https://citoapi.com/contact/", "email": "support@citoapi.com" }, "license": { "name": "Proprietary API, MIT-licensed clients", "url": "https://citoapi.com/terms/" } }, "externalDocs": { "description": "UFC API documentation", "url": "https://citoapi.com/docs/api/ufc/" }, "servers": [ { "url": "https://api.citoapi.com/api/v1", "description": "Production" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Fighters", "description": "Fighter profiles, career statistics and fight history." }, { "name": "Events", "description": "UFC events, cards and schedules." }, { "name": "Bouts", "description": "Individual fights, results and round statistics." }, { "name": "Rankings", "description": "Divisional rankings, champions and the media panel board." }, { "name": "Odds", "description": "Betting odds by market and bookmaker, where coverage exists." }, { "name": "Live", "description": "Live fight-night state for in-progress bouts." }, { "name": "Search", "description": "Resolve names to slugs." } ], "paths": { "/ufc": { "get": { "tags": [ "Fighters" ], "operationId": "getUfcCoverage", "summary": "Coverage map", "description": "Entity counts and the current endpoint map. A good first call.", "responses": { "200": { "description": "Coverage index", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Coverage" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/search": { "get": { "tags": [ "Search" ], "operationId": "searchUfc", "summary": "Search fighters and events", "description": "Resolve a name to the slug used by every other endpoint. Use this first.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 }, "description": "Fighter or event name" } ], "responses": { "200": { "description": "Matching fighters and events", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SearchResults" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/fighters": { "get": { "tags": [ "Fighters" ], "operationId": "listFighters", "summary": "List fighters", "description": "Paginated fighter directory.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Items per page" }, { "name": "division", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Fighter" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/fighters/{slug}": { "get": { "tags": [ "Fighters" ], "operationId": "getFighter", "summary": "Get a fighter", "description": "Profile: record, division, champion status, physical attributes, gym, country, headshot.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fighter slug, e.g. `islam-makhachev`" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Fighter" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/fighters/{slug}/stats": { "get": { "tags": [ "Fighters" ], "operationId": "getFighterStats", "summary": "Get a fighter's career statistics", "description": "Career rates: strikes landed and absorbed per minute, accuracy and defence, takedown and submission averages, strike splits by target and position, and win-by-method.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fighter slug" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FighterStats" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/fighters/{slug}/fights": { "get": { "tags": [ "Fighters" ], "operationId": "getFighterFights", "summary": "Get a fighter's fight history", "description": "Completed bouts newest first, each with opponent, event and result.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fighter slug" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FighterFight" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/fighters/{slug}/style": { "get": { "tags": [ "Fighters" ], "operationId": "getFighterStyle", "summary": "Get a fighter's style profile", "description": "Fighting style from official round stats across UFC, DWCS, Road to UFC and the MMA archives: four labels (striker, clinch, wrestler, submission) scored 0-1 against every fighter with 3+ stat bouts, the primary style, and the numbers behind them (position, target, grappling, absorbed). `sample.lowConfidence` is true under 3 stat bouts. `tentative.pressureVsOutfighter` is inferred from pace and exchange balance, not an official classification. Free and Starter keys get a profile from bouts inside their history window.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Fighter slug, e.g. `max-holloway`" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FighterStyle" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/events": { "get": { "tags": [ "Events" ], "operationId": "listEvents", "summary": "List events", "description": "The event archive, newest first.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Items per page" }, { "name": "hasStats", "in": "query", "schema": { "type": "boolean" }, "description": "Only events with statistic coverage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/events/upcoming": { "get": { "tags": [ "Events" ], "operationId": "listUpcomingEvents", "summary": "List upcoming events", "description": "The forward schedule including numbered cards, Fight Nights and Contender Series.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/events/recent": { "get": { "tags": [ "Events" ], "operationId": "listRecentEvents", "summary": "List recent events", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/events/{eventIdOrSlug}": { "get": { "tags": [ "Events" ], "operationId": "getEvent", "summary": "Get an event", "parameters": [ { "name": "eventIdOrSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Event id or slug" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Event" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/events/{eventIdOrSlug}/bouts": { "get": { "tags": [ "Events" ], "operationId": "getEventBouts", "summary": "Get an event's fight card", "description": "The full card in card order — main event first, then the rest of the main card, prelims and early prelims.", "parameters": [ { "name": "eventIdOrSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Event id or slug" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Bout" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/events/{eventIdOrSlug}/odds": { "get": { "tags": [ "Odds" ], "operationId": "getEventOdds", "summary": "Get odds for a card", "description": "Card odds by fight, market and bookmaker. An empty `markets` array is a coverage state, not an error.", "parameters": [ { "name": "eventIdOrSlug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Event id or slug" }, { "name": "bookmaker", "in": "query", "schema": { "type": "string", "default": "all" }, "description": "`all`, `draftkings`, `fanduel`, …" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Odds" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/bouts": { "get": { "tags": [ "Bouts" ], "operationId": "listBouts", "summary": "List bouts", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Items per page" }, { "name": "hasStats", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Bout" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/bouts/{boutId}": { "get": { "tags": [ "Bouts" ], "operationId": "getBout", "summary": "Get a bout", "parameters": [ { "name": "boutId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bout id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Bout" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/bouts/{boutId}/stats": { "get": { "tags": [ "Bouts" ], "operationId": "getBoutStats", "summary": "Get per-fighter totals for a bout", "parameters": [ { "name": "boutId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bout id" }, { "name": "round", "in": "query", "schema": { "type": "integer" }, "description": "Restrict to one round" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoundStats" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/bouts/{boutId}/rounds": { "get": { "tags": [ "Bouts" ], "operationId": "getBoutRounds", "summary": "Get round-by-round statistics", "description": "One row per fighter per round: significant and total strikes, takedowns, submission attempts, reversals, knockdowns and control time, with target and position splits.", "parameters": [ { "name": "boutId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bout id" }, { "name": "round", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoundStats" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/bouts/{boutId}/odds": { "get": { "tags": [ "Odds" ], "operationId": "getBoutOdds", "summary": "Get odds for a bout", "parameters": [ { "name": "boutId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bout id" }, { "name": "bookmaker", "in": "query", "schema": { "type": "string", "default": "all" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Odds" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/rankings": { "get": { "tags": [ "Rankings" ], "operationId": "getRankings", "summary": "Get rankings", "description": "All divisions on a board. Champions carry `rankText` `C`.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RankingEntry" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/rankings/meta": { "get": { "tags": [ "Rankings" ], "operationId": "getMetaRankings", "summary": "Get the Meta rankings board", "description": "The algorithmic board, typically updated Mondays.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RankingEntry" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/rankings/meta/{division}": { "get": { "tags": [ "Rankings" ], "operationId": "getMetaRankingsByDivision", "summary": "Get the Meta board for one division", "parameters": [ { "name": "division", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Division slug, e.g. `lightweight`" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RankingEntry" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/rankings/media": { "get": { "tags": [ "Rankings" ], "operationId": "getMediaRankings", "summary": "Get the media-panel rankings board", "description": "The media panel board, typically updated Tuesdays.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RankingEntry" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/rankings/media/{division}": { "get": { "tags": [ "Rankings" ], "operationId": "getMediaRankingsByDivision", "summary": "Get the media board for one division", "parameters": [ { "name": "division", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Division slug, e.g. `lightweight`" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RankingEntry" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/live": { "get": { "tags": [ "Live" ], "operationId": "getLiveOverview", "summary": "Live overview", "description": "Active bouts, feed lag and a recommended poll interval.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/ufc/live/health": { "get": { "tags": [ "Live" ], "operationId": "getLiveHealth", "summary": "Live feed health", "description": "Worker health and lag. Check this before trusting live data in production.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/ufc/live/{boutId}/state": { "get": { "tags": [ "Live" ], "operationId": "getLiveBoutState", "summary": "Get live bout state", "description": "Compact current state for polling: round, clock, status and per-corner counts.", "parameters": [ { "name": "boutId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bout id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LiveState" }, "meta": { "type": "object" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ufc/live/events": { "get": { "tags": [ "Live" ], "operationId": "listLiveEvents", "summary": "List live events", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or quota reached. Honour the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your Cito API key. Free tier: https://citoapi.com/signup/" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "not_found", "rate_limited", "unauthorized" ] }, "message": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this to support" } } } } }, "ListMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } } }, "Coverage": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "coverage": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Entity counts, e.g. fighters, events, bouts, roundStats" }, "endpoints": { "type": "object", "additionalProperties": { "type": "string" } } } }, "Record": { "type": "object", "properties": { "wins": { "type": [ "integer", "null" ] }, "losses": { "type": [ "integer", "null" ] }, "draws": { "type": [ "integer", "null" ] }, "noContest": { "type": [ "integer", "null" ] }, "text": { "type": "string", "examples": [ "29-1-0 (W-L-D)" ] } } }, "Fighter": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string", "examples": [ "islam-makhachev" ] }, "name": { "type": "string" }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "nickname": { "type": [ "string", "null" ] }, "division": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "isActive": { "type": [ "boolean", "null" ] }, "championStatus": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "placeOfBirth": { "type": [ "string", "null" ] }, "trainsAt": { "type": [ "string", "null" ] }, "fightingStyle": { "type": [ "string", "null" ] }, "age": { "type": [ "integer", "null" ] }, "heightInches": { "type": [ "string", "null" ] }, "weightLbs": { "type": [ "string", "null" ] }, "reachInches": { "type": [ "string", "null" ] }, "legReachInches": { "type": [ "string", "null" ] }, "stance": { "type": [ "string", "null" ] }, "octagonDebut": { "type": [ "string", "null" ], "format": "date-time" }, "record": { "$ref": "#/components/schemas/Record" }, "recordText": { "type": [ "string", "null" ] }, "headshotUrl": { "type": [ "string", "null" ] }, "bodyImageUrl": { "type": [ "string", "null" ] }, "proxiedImageUrl": { "type": [ "string", "null" ], "description": "CORS-safe image URL — use this in browsers." } } }, "FighterStyle": { "type": "object", "properties": { "fighter": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } }, "primaryStyle": { "type": [ "string", "null" ], "enum": [ "striker", "clinch", "wrestler", "submission", null ] }, "labels": { "type": "array", "items": { "type": "object", "properties": { "style": { "type": "string", "enum": [ "striker", "clinch", "wrestler", "submission" ] }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "level": { "type": "string" }, "primary": { "type": "boolean" }, "basis": { "type": "string" } } } }, "sample": { "type": "object", "properties": { "bouts": { "type": "integer" }, "rounds": { "type": "integer" }, "minutes": { "type": "number" }, "byPromotion": { "type": "object", "additionalProperties": { "type": "integer" } }, "lowConfidence": { "type": "boolean" } } }, "striker": { "type": "object", "description": "subtype (volume, precision, volume-and-precision, balanced, low-output), volume, accuracy, knockdowns." }, "position": { "type": "object", "description": "Share of significant strikes landed at distance, in the clinch and on the ground." }, "target": { "type": "object", "description": "Share of significant strikes landed to the head, body and legs." }, "grappling": { "type": "object", "description": "Takedowns per 15 min and accuracy, control share, submission attempts per 15 min, reversals." }, "absorbed": { "type": "object", "description": "Opponents' strikes and takedowns against the fighter, striking defence, control against." }, "tentative": { "type": "object", "properties": { "pressureVsOutfighter": { "type": "object", "properties": { "tag": { "type": "string", "enum": [ "pressure", "outfighter", "neither" ] }, "tentative": { "type": "boolean", "enum": [ true ] }, "basis": { "type": "string" } } } } } } }, "FighterStats": { "type": "object", "properties": { "fighterSlug": { "type": "string" }, "strikingAccuracy": { "type": [ "string", "null" ] }, "significantStrikesLanded": { "type": [ "integer", "null" ] }, "significantStrikesAttempted": { "type": [ "integer", "null" ] }, "takedownAccuracy": { "type": [ "string", "null" ] }, "takedownsLanded": { "type": [ "integer", "null" ] }, "takedownsAttempted": { "type": [ "integer", "null" ] }, "sigStrikesLandedPerMin": { "type": [ "string", "null" ] }, "sigStrikesAbsorbedPerMin": { "type": [ "string", "null" ] }, "takedownAvgPer15Min": { "type": [ "string", "null" ] }, "submissionAvgPer15Min": { "type": [ "string", "null" ] }, "sigStrikeDefense": { "type": [ "string", "null" ] }, "takedownDefense": { "type": [ "string", "null" ] }, "knockdownAvg": { "type": [ "string", "null" ] }, "averageFightTimeSeconds": { "type": [ "integer", "null" ] }, "sigStrikesByPosition": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/StrikeSplit" } }, "sigStrikesByTarget": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/StrikeSplit" } }, "winsByMethod": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/StrikeSplit" } } } }, "StrikeSplit": { "type": "object", "properties": { "label": { "type": [ "string", "null" ] }, "count": { "type": [ "integer", "null" ] }, "percent": { "type": [ "number", "null" ] } } }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string", "examples": [ "cryptocom-ufc-331" ] }, "title": { "type": "string" }, "shortTitle": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "venue": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "locationText": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "hasStats": { "type": [ "boolean", "null" ] }, "eventDate": { "type": [ "string", "null" ], "format": "date" }, "eventWeekday": { "type": [ "string", "null" ] }, "eventTimeZone": { "type": [ "string", "null" ] }, "venueTimeZone": { "type": [ "string", "null" ] } } }, "BoutFighter": { "type": "object", "properties": { "fighterId": { "type": [ "string", "null" ] }, "fighterSlug": { "type": [ "string", "null" ] }, "fighterName": { "type": [ "string", "null" ] }, "corner": { "type": [ "string", "null" ], "enum": [ "red", "blue", null ] }, "outcome": { "type": [ "string", "null" ] }, "rankText": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "flag": { "type": [ "string", "null" ] }, "championStatus": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] } } }, "Bout": { "type": "object", "properties": { "id": { "type": "string" }, "eventSlug": { "type": [ "string", "null" ] }, "weightClass": { "type": [ "string", "null" ] }, "cardSection": { "type": [ "string", "null" ], "examples": [ "Main Card", "Prelims" ] }, "cardPosition": { "type": [ "string", "null" ] }, "boutOrder": { "type": [ "integer", "null" ] }, "status": { "type": [ "string", "null" ] }, "titleBout": { "type": [ "boolean", "null" ] }, "isCancelled": { "type": [ "boolean", "null" ] }, "winnerFighterSlug": { "type": [ "string", "null" ] }, "method": { "type": [ "string", "null" ], "examples": [ "KO/TKO", "Submission", "Decision - Unanimous" ] }, "resultRound": { "type": [ "integer", "null" ] }, "resultTime": { "type": [ "string", "null" ] }, "referee": { "type": [ "string", "null" ] }, "hasStats": { "type": [ "boolean", "null" ] }, "fighters": { "type": "array", "items": { "$ref": "#/components/schemas/BoutFighter" } } } }, "FighterFight": { "type": "object", "description": "A flattened history row: the fighter, the opponent and the event at the top level.", "properties": { "fighterSlug": { "type": [ "string", "null" ] }, "fighterName": { "type": [ "string", "null" ] }, "championStatus": { "type": [ "string", "null" ] }, "corner": { "type": [ "string", "null" ] }, "outcome": { "type": [ "string", "null" ], "examples": [ "win", "loss", "draw" ] }, "opponent": { "$ref": "#/components/schemas/BoutFighter" }, "event": { "$ref": "#/components/schemas/Event" }, "bout": { "$ref": "#/components/schemas/Bout" } } }, "RoundStats": { "type": "object", "properties": { "boutId": { "type": "string" }, "fighterSlug": { "type": [ "string", "null" ] }, "fighterName": { "type": [ "string", "null" ] }, "round": { "type": [ "integer", "null" ] }, "knockdowns": { "type": [ "integer", "null" ] }, "significantStrikes": { "type": [ "string", "null" ], "description": "Combined `landed of attempted`, e.g. `3 of 5`" }, "totalStrikes": { "type": [ "string", "null" ] }, "takedowns": { "type": [ "string", "null" ] }, "submissionAttempts": { "type": [ "integer", "null" ] }, "reversals": { "type": [ "integer", "null" ] }, "controlTime": { "type": [ "string", "null" ], "description": "Clock format, e.g. `0:11`" }, "head": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "leg": { "type": [ "string", "null" ] }, "distance": { "type": [ "string", "null" ] }, "clinch": { "type": [ "string", "null" ] }, "ground": { "type": [ "string", "null" ] } } }, "RankingEntry": { "type": "object", "properties": { "id": { "type": "string" }, "system": { "type": "string", "enum": [ "meta", "media" ] }, "division": { "type": "string" }, "normalizedDivision": { "type": "string" }, "rank": { "type": [ "integer", "null" ] }, "rankText": { "type": "string", "description": "Numeric rank, or `C` for champion" }, "rankChange": { "type": [ "integer", "null" ] }, "fighterSlug": { "type": [ "string", "null" ] }, "fighterName": { "type": [ "string", "null" ] }, "isChampion": { "type": [ "boolean", "null" ] }, "country": { "type": [ "string", "null" ] }, "flag": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "fighter": { "$ref": "#/components/schemas/Fighter" } } }, "OddsOutcome": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "bookmaker": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "americanOdds": { "type": [ "integer", "null" ] }, "decimalOdds": { "type": [ "number", "null" ] }, "impliedProbability": { "type": [ "number", "null" ] } } }, "OddsMarket": { "type": "object", "properties": { "key": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/OddsOutcome" } } } }, "Odds": { "type": "object", "description": "An empty `markets` array is a coverage state, not an error.", "properties": { "boutId": { "type": [ "string", "null" ] }, "bookmaker": { "type": [ "string", "null" ] }, "markets": { "type": "array", "items": { "$ref": "#/components/schemas/OddsMarket" } } } }, "LiveState": { "type": "object", "properties": { "boutId": { "type": [ "string", "null" ] }, "eventSlug": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "examples": [ "live", "armed", "completed" ] }, "currentRound": { "type": [ "integer", "null" ] }, "currentTime": { "type": [ "string", "null" ] }, "lagSeconds": { "type": [ "number", "null" ] }, "liveStats": { "type": "object", "additionalProperties": { "type": "object", "properties": { "sigStrikes": { "type": [ "integer", "null" ] }, "takedowns": { "type": [ "integer", "null" ] } } } } } }, "SearchResults": { "type": "object", "properties": { "fighters": { "type": "array", "items": { "$ref": "#/components/schemas/Fighter" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } } } }