{
  "openapi": "3.0.3",
  "info": {
    "title": "Fight Forensics MMA API",
    "version": "1.0.0",
    "description": "Free, read-only JSON API over the Fight Forensics MMA dataset. Leads with derived career-Elo rankings plus fighters, events and organizations. Keyless free tier is rate-limited per IP; send a free API key in the X-Api-Key header for higher limits. Data compiled by Fight Forensics (fightforensics.com) from public MMA records; use with attribution and a link back.",
    "contact": { "name": "Fight Forensics", "url": "https://fightforensics.com/docs" }
  },
  "servers": [{ "url": "https://fightforensics.com/api/v1" }],
  "security": [{}, { "ApiKeyAuth": [] }],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key" }
    },
    "parameters": {
      "limit": { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Page size (capped per endpoint)." },
      "offset": { "name": "offset", "in": "query", "schema": { "type": "integer" }, "description": "Rows to skip." }
    },
    "responses": {
      "NotFound": { "description": "No matching resource.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } },
      "RateLimited": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } } }
    }
  },
  "paths": {
    "/": {
      "get": { "summary": "API discovery root", "responses": { "200": { "description": "Available endpoints, docs and attribution." } } }
    },
    "/stats": {
      "get": { "summary": "Dataset summary — counts of fighters, bouts, events, promotions, venues, countries and referees", "responses": { "200": { "description": "Dataset counts (cached hourly)." } } }
    },
    "/rankings": {
      "get": {
        "summary": "Career-Elo fighter rankings (the flagship derived metric)",
        "parameters": [
          { "name": "active", "in": "query", "schema": { "type": "boolean" }, "description": "Limit to fighters who fought recently." },
          { "$ref": "#/components/parameters/limit" },
          { "$ref": "#/components/parameters/offset" }
        ],
        "responses": { "200": { "description": "Ranked fighters by career Elo." }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/rankings/decade/{startYear}": {
      "get": {
        "summary": "Career-Elo rankings computed within a decade",
        "parameters": [
          { "name": "startYear", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Decade start, e.g. 2010." },
          { "$ref": "#/components/parameters/limit" }
        ],
        "responses": { "200": { "description": "In-decade Elo rankings." }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/fighters": {
      "get": {
        "summary": "List / search fighters",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Name search (case-insensitive substring)." },
          { "name": "stance", "in": "query", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/limit" },
          { "$ref": "#/components/parameters/offset" }
        ],
        "responses": { "200": { "description": "Fighters page." } }
      }
    },
    "/fighters/{id}": {
      "get": {
        "summary": "Fighter profile with record and recent bouts",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }],
        "responses": { "200": { "description": "Fighter profile." }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/events": {
      "get": {
        "summary": "List events",
        "parameters": [
          { "name": "org", "in": "query", "schema": { "type": "integer", "format": "int64" }, "description": "Filter by organization id." },
          { "name": "year", "in": "query", "schema": { "type": "integer" } },
          { "$ref": "#/components/parameters/limit" },
          { "$ref": "#/components/parameters/offset" }
        ],
        "responses": { "200": { "description": "Events page." } }
      }
    },
    "/events/{id}": {
      "get": {
        "summary": "Event card with full bout list",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }],
        "responses": { "200": { "description": "Event with bouts." }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/organizations": {
      "get": {
        "summary": "List organizations / promotions",
        "parameters": [
          { "$ref": "#/components/parameters/limit" },
          { "$ref": "#/components/parameters/offset" }
        ],
        "responses": { "200": { "description": "Organizations page." } }
      }
    },
    "/organizations/{id}": {
      "get": {
        "summary": "Organization profile with recent events",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }],
        "responses": { "200": { "description": "Organization profile." }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    }
  }
}