FightForensics
API Documentation

The MMA
data API

A free, read-only JSON API over the Fight Forensics dataset. Versioned at /api/v1, CORS-open, and cache-friendly. Data compiled from public MMA records; free to use with attribution and a link back.

Getting started

Every endpoint is a plain GET that returns JSON. Base URL:

https://fightforensics.com/api/v1

Every request needs a free API key in the X-Api-Key header. Request one, it's free, issued to sites that show a visible link back to fightforensics.com. Then:

curl -H "X-Api-Key: ff_your_key" https://fightforensics.com/api/v1/rankings?limit=3

Authentication & limits

  • Key required: requests without an X-Api-Key header return 401. Only /api/v1 and openapi.json are open.
  • Free API key: allows 120 req/min and 5,000 req/day. Send it in the X-Api-Key header on every request.
  • Get a key: request one here. Free, issued to sites that display a visible link back to fightforensics.com.
curl -H "X-Api-Key: ff_your_key" https://fightforensics.com/api/v1/rankings

Exceeding a limit returns 429 with a Retry-After header. Deep pagination is capped (offset ≤ 1,000): filter instead of walking the whole dataset. Responses set Cache-Control so you (and the edge) can cache freely. Use is subject to the terms of use.

Endpoints

GET /api/v1/statsDataset summary: counts of fighters, bouts, events, promotions, venues, countries, referees, and the year span.
GET /api/v1/rankingsCareer-Elo leaderboard. Query: active (bool), limit, offset.
GET /api/v1/rankings/decade/{startYear}Career-Elo computed within a decade, e.g. 2010.
GET /api/v1/fightersList / search fighters. Query: q, stance, limit, offset.
GET /api/v1/fighters/{id}Fighter profile: record + recent bouts with opponents.
GET /api/v1/eventsList events. Query: org, year, limit, offset.
GET /api/v1/events/{id}Event card with the full bout list.
GET /api/v1/organizationsList promotions. Query: limit, offset.
GET /api/v1/organizations/{id}Promotion profile with recent events.

Full machine-readable contract: openapi.json, import into Postman/Insomnia or generate a client.

Example response

GET /api/v1/rankings?active=true&limit=2

{
  "dataset": "Career-Elo fighter rankings",
  "api_version": "v1",
  "attribution": "Data compiled by Fight Forensics …",
  "scope": "active",
  "rankings": [
    { "rank": 1, "elo": 1948.5, "fighter_id": 30,
      "name": "Islam Makhachev",
      "url": "https://fightforensics.com/fighter/30/islam-makhachev" },
    { "rank": 2, "elo": 1939.6, "fighter_id": 415,
      "name": "Jon Jones", "url": "https://fightforensics.com/fighter/415/jon-jones" }
  ]
}