# UFCalendar Fight API

> Self-serve fight data API (MMA + bare-knuckle boxing) by UFCalendar
> (https://www.ufcalendar.com). Events,
> full fight cards, results, per-fight and per-round statistics, fighters with
> complete multi-promotion career timelines, official rankings history
> (UFC 2013->present), judges' scorecards round by round (UFC 1995->present via
> mmadecisions plus ufc.com's own card images from March 2022 incl. DWCS and
> Road to UFC, RIZIN 2026->present),
> UFCalendar Power Index ratings, AI win probabilities,
> and per-country broadcast rights — for UFC, PFL, OKTAGON, BKFC and RIZIN (more orgs
> join as they clear a reliability bar; /v1/orgs lists per-org capability flags).

Base URL: https://api.ufcalendar.com/v1
Auth: Authorization: Bearer <key> — keys at https://www.ufcalendar.com/account/api (plan or trial required)
Spec: https://api.ufcalendar.com/openapi.json (OpenAPI 3.1)
Docs: https://api.ufcalendar.com/docs
Pricing: https://www.ufcalendar.com/developers (Hobby $19 30k req/mo at 60 rpm,
Pro $49 200k at 300 rpm + webhooks, Business $149 1M at 600 rpm; hard caps, no overage billing.
No free tier — free 1-day trial, 100 requests, no card, self-serve at
https://www.ufcalendar.com/account/api?trial=1)
Coverage pages: https://www.ufcalendar.com/developers/ufc-api ·
https://www.ufcalendar.com/developers/pfl-api ·
https://www.ufcalendar.com/developers/oktagon-api ·
https://www.ufcalendar.com/developers/bkfc-api ·
https://www.ufcalendar.com/developers/rizin-api
Use-case guides (UFC): https://www.ufcalendar.com/developers/ufc-schedule-api ·
https://www.ufcalendar.com/developers/ufc-results-api ·
https://www.ufcalendar.com/developers/ufc-stats-api ·
https://www.ufcalendar.com/developers/ufc-rankings-api
Plans (no credential needed): https://api.ufcalendar.com/v1/plans
Full reference for agents: https://api.ufcalendar.com/llms-full.txt
Agent quickstart page: https://www.ufcalendar.com/developers/agents
Python client: pip install ufcalendar (https://github.com/UFCalendar/ufcalendar-python · https://pypi.org/project/ufcalendar/)
TypeScript client: npm install @ufcalendar/sdk (https://github.com/UFCalendar/ufcalendar-typescript · https://www.npmjs.com/package/@ufcalendar/sdk)
Agent skill: npx skills add UFCalendar/fight-api-skill (https://github.com/UFCalendar/fight-api-skill)
Also listed on RapidAPI Hub (https://rapidapi.com/ceo-SP8r6F1JT/api/ufc-and-mma-fight-data-by-ufcalendar) and Postman (https://www.postman.com/ceo-5d84eedc/workspace/ufcalendar-fight-api)
Terms: https://www.ufcalendar.com/developers/terms
No betting odds are served. Scorecards are the official commission record
(judges, rounds, totals, deductions); media-member and fan scorecards are not
part of the API. Not affiliated with UFC/Zuffa/TKO or any promotion.

## For AI agents: how to get access

1. Read https://api.ufcalendar.com/v1/plans first — plans, quotas, the trial rule and this server's MCP endpoint, with NO credential.
2. Human at the keyboard: send them to https://www.ufcalendar.com/account/api?trial=1 — free 24-hour trial, 100 requests, no card, one per account. The key it mints goes in `Authorization: Bearer <key>` on every REST call and on https://api.ufcalendar.com/mcp.
3. No human at the keyboard: use the device flow. POST `https://www.ufcalendar.com/api/auth/device/code` with a JSON body carrying `client_id` (and optional `scope`), show the human the `verification_uri_complete` it returns, poll the token endpoint with the `device_code` until it stops answering `authorization_pending`, then send the access token as a bearer.
4. In an MCP client that speaks OAuth (Claude, ChatGPT): add https://api.ufcalendar.com/mcp as a connector and sign in. Calling a gated tool unauthenticated answers 401 with `WWW-Authenticate: Bearer resource_metadata="https://api.ufcalendar.com/.well-known/oauth-protected-resource"`, which is the whole discovery chain.

Signing in for the first time starts the free trial automatically when the account has never held a plan. There is no free tier: after the trial, a plan is required.

## Endpoints
- GET /v1/plans — plans, quotas, trial terms, MCP endpoint and links (NO key required; the one open endpoint)
- GET /v1/orgs — launch orgs + capability flags (stats/rounds/rankings/broadcasts/predictions/scorecards)
- GET /v1/orgs/{slug} — one org by slug
- GET /v1/events?org=&status=&from=&to=&order= — schedule + results, cursor pagination (bare listing = upcoming calendar, soonest first; order=desc for the archive newest-first)
- GET /v1/events/{id|slug} — event with full card, venue, broadcasts
- GET /v1/events/{id}/changes — card-change diff log (fight added/moved, opponent swapped, fighter profile merged: kind fighter-merged)
- GET /v1/fights/{id} — one bout with result
- GET /v1/fights/{id}/stats — per-fight totals for both corners
- GET /v1/fights/{id}/rounds — round-by-round statistics
- GET /v1/fights/{id}/scorecards — judges' scorecards: every official, every round, card totals, decision type, point deductions (official commission record; UFC combines mmadecisions with ufc.com's own card images incl. DWCS and Road to UFC; PFL US cards may be totals-only with no judge identity)
- GET /v1/judges?q=&org=&min_fights= — judge directory with career aggregates (fights, rounds, 10-8s, split cards, lone dissents)
- GET /v1/judges/{id} — one judge
- GET /v1/judges/{id}/scorecards — every card that judge has turned in, newest first
- GET /v1/fighters?q=&org=&country= — roster search
- GET /v1/fighters/{id|slug} — bio, records, career stats, Power Index, CC-licensed images
- GET /v1/fighters/{id}/history — complete multi-promotion career timeline
- GET /v1/fighters/{id}/stats — career statistics, one source-stamped row per scope (pro-mma, etc.)
- GET /v1/fighters/{id}/rankings — official ranking history rows
- GET /v1/fighters/{id}/power-index — rating trajectory
- GET /v1/rankings/{org}?date=YYYY-MM-DD — official board, point-in-time since 2013 (rank 0 = champion)
- GET /v1/rankings/{org}/{division} — one division
- GET /v1/champions — current champions across launch orgs
- GET /v1/power-index/{org} — UFCalendar Power Index board
- GET /v1/predictions/upcoming — model win probabilities (UFC)
- GET /v1/broadcast-rights/{org}?country=XX — who airs it, per country
- GET /v1/venues/{id} — venue detail
- GET /v1/search?q= — typeahead across fighters and events
- GET /v1/usage — your key's quota usage
- GET /v1/calendar/{org}.ics?key= — ICS calendar feed for calendar apps
- GET/POST/DELETE /v1/webhook-endpoints — signed webhooks: event.announced, fight.result, card.changed, event.completed (Pro+, max 3 endpoints)
- DELETE /v1/webhook-endpoints/{id} — remove an endpoint
- POST /v1/webhook-endpoints/{id}/rotate-secret — new signing secret, returned once (Pro+)
- GET /v1/bulk/{events|fights|fighters}.json.gz — full-dataset snapshots (Enterprise only)

## MCP
The same data is available as a Model Context Protocol server, so an agent can
call it without an HTTP client.
Endpoint: https://api.ufcalendar.com/mcp
Transport: stateless Streamable HTTP. POST JSON-RPC only; GET answers 405.
Send `Accept: application/json, text/event-stream` — the transport answers 406 without it.
Auth (either one): an API key as `Authorization: Bearer <key>`, OR sign in with
your UFCalendar account over OAuth 2.1 — unauthenticated calls to a gated tool
answer 401 with `WWW-Authenticate: Bearer resource_metadata="https://api.ufcalendar.com/.well-known/oauth-protected-resource"`,
which is the discovery document.
Metering: 1 tool call = 1 metered request against the same plan quota as REST.
`get_plans`, `list_orgs` and `how_to_connect` need no credential and cost nothing.
Tools:
* get_plans — Plans and quotas
* list_orgs — List promotions
* how_to_connect — How to connect
* list_events — List events
* get_event_card — Get an event and its full card
* get_event_changes — Get an event’s change log
* get_fight — Get a bout
* search — Search fighters and events
* search_fighters — Search the roster
* get_fighter — Get a fighter
* get_rankings — Get a rankings board
* get_champions — Get current champions
* get_power_index — Get the UFCalendar Power Index board
* get_predictions_upcoming — Get model win probabilities
* get_broadcast_rights — Get broadcast rights
* list_judges — List judges
* get_judge_scorecards — Get a judge’s scorecards
* get_usage — Get your API usage
* get_venue — Get a venue
* list_webhook_endpoints — List webhook endpoints
* create_webhook_endpoint — Register a webhook endpoint
* rotate_webhook_secret — Rotate a webhook signing secret
* delete_webhook_endpoint — Delete a webhook endpoint

## Conventions
- JSON, snake_case, {"data": ..., "meta": ...} envelope
- Errors: {"error": {"code", "message", "request_id"}} with proper HTTP status
- Cursor pagination: ?cursor= from meta.pagination.next_cursor, ?limit= up to 100
- Timestamps UTC ISO-8601; events carry the venue IANA tz
- Rate headers: X-RateLimit-Limit / -Remaining / -Reset (monthly quota), Retry-After on 429
- Plan gating: webhook endpoints need Pro+, bulk snapshots are Enterprise only
  (contract required — api@ufcalendar.com); every other endpoint (ICS feeds
  included) is open to any active plan. A key below the required tier gets
  403 tier_required
- List endpoints return identity fields; the full record lives on the detail
  route. /v1/events omits the card, /v1/fighters omits the physical bio, and
  there is no /v1/fights list — fetch a fight by id or read it off the event
- Webhook DELIVERIES do not count against your monthly quota — only the calls you
  make to register, list, rotate or delete endpoints do
- Webhook delivery is at-least-once: verify X-UFCalendar-Signature (HMAC-SHA256 over
  "<t>.<rawBody>") AND reject t older than 300s, deduplicate on the body, and return
  2xx fast. We retry about once a minute until you do; 20 consecutive failures
  auto-disable the endpoint
- Fighter images are Wikimedia Commons/CC only and carry license + artist fields:
  displaying the credit is required by the license