{
 "openapi": "3.1.0",
 "info": {
  "title": "Belt Holders API",
  "version": "2026-10-03",
  "summary": "Lineal championship belts for every league, as static JSON, CSV, RSS and iCalendar.",
  "description": "Read-only. Every file is regenerated by the site build every couple of hours; no keys, no rate limits beyond GitHub Pages' own. Data is CC BY 4.0: credit beltholders.com. The sister sites publish the same shapes at https://collegefootballbelt.com/api/current.json and https://collegebasketballbelt.com/api/current.json (women's belt under /women/api/).",
  "contact": {
   "name": "R&O Holdings LLC",
   "url": "https://beltholders.com/about/"
  },
  "license": {
   "name": "CC BY 4.0",
   "url": "https://creativecommons.org/licenses/by/4.0/"
  }
 },
 "servers": [
  {
   "url": "https://beltholders.com"
  }
 ],
 "paths": {
  "/api/current.json": {
   "get": {
    "summary": "Every pro belt's holder and next defense",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "site": {
           "type": "string"
          },
          "generated": {
           "type": "string",
           "format": "date"
          },
          "leagues": {
           "type": "object",
           "additionalProperties": {
            "type": "object",
            "properties": {
             "name": {
              "type": "string"
             },
             "holder": {
              "type": "string"
             },
             "holder_short": {
              "type": "string"
             },
             "since": {
              "type": "string",
              "format": "date"
             },
             "defenses": {
              "type": "integer"
             },
             "reign_no": {
              "type": "integer"
             },
             "state": {
              "type": "string",
              "description": "in_season_next_game, offseason_schedule_pending, postseason_holder_out, ..."
             },
             "data_ok": {
              "type": "boolean"
             },
             "url": {
              "type": "string",
              "format": "uri"
             },
             "next": {
              "type": [
               "object",
               "null"
              ],
              "properties": {
               "date": {
                "type": "string",
                "format": "date"
               },
               "time_et": {
                "type": [
                 "string",
                 "null"
                ],
                "description": "HH:MM Eastern, null when not set"
               },
               "opponent": {
                "type": "string"
               },
               "opponent_short": {
                "type": "string"
               },
               "home": {
                "type": "boolean"
               },
               "neutral": {
                "type": "boolean"
               },
               "venue": {
                "type": [
                 "string",
                 "null"
                ]
               },
               "city": {
                "type": [
                 "string",
                 "null"
                ]
               },
               "tv": {
                "type": [
                 "string",
                 "null"
                ]
               },
               "win_prob": {
                "type": [
                 "number",
                 "null"
                ]
               },
               "url": {
                "type": "string",
                "format": "uri"
               }
              }
             }
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/network.json": {
   "get": {
    "summary": "Every belt on all three sites (pro, college football, men's and women's college basketball)",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "generated": {
           "type": "string"
          },
          "belts": {
           "type": "array",
           "items": {
            "allOf": [
             {
              "type": "object",
              "properties": {
               "name": {
                "type": "string"
               },
               "holder": {
                "type": "string"
               },
               "holder_short": {
                "type": "string"
               },
               "since": {
                "type": "string",
                "format": "date"
               },
               "defenses": {
                "type": "integer"
               },
               "reign_no": {
                "type": "integer"
               },
               "state": {
                "type": "string",
                "description": "in_season_next_game, offseason_schedule_pending, postseason_holder_out, ..."
               },
               "data_ok": {
                "type": "boolean"
               },
               "url": {
                "type": "string",
                "format": "uri"
               },
               "next": {
                "type": [
                 "object",
                 "null"
                ],
                "properties": {
                 "date": {
                  "type": "string",
                  "format": "date"
                 },
                 "time_et": {
                  "type": [
                   "string",
                   "null"
                  ],
                  "description": "HH:MM Eastern, null when not set"
                 },
                 "opponent": {
                  "type": "string"
                 },
                 "opponent_short": {
                  "type": "string"
                 },
                 "home": {
                  "type": "boolean"
                 },
                 "neutral": {
                  "type": "boolean"
                 },
                 "venue": {
                  "type": [
                   "string",
                   "null"
                  ]
                 },
                 "city": {
                  "type": [
                   "string",
                   "null"
                  ]
                 },
                 "tv": {
                  "type": [
                   "string",
                   "null"
                  ]
                 },
                 "win_prob": {
                  "type": [
                   "number",
                   "null"
                  ]
                 },
                 "url": {
                  "type": "string",
                  "format": "uri"
                 }
                }
               }
              }
             },
             {
              "type": "object",
              "properties": {
               "key": {
                "type": "string"
               },
               "sport": {
                "type": "string"
               },
               "site": {
                "type": "string"
               },
               "short": {
                "type": "string"
               },
               "colors": {
                "type": "array",
                "items": {
                 "type": "string"
                }
               },
               "badge": {
                "type": [
                 "string",
                 "null"
                ]
               },
               "feed": {
                "type": [
                 "string",
                 "null"
                ]
               },
               "ok": {
                "type": "boolean"
               }
              }
             }
            ]
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/{league}/api/reigns.json": {
   "get": {
    "summary": "Every reign of one belt",
    "parameters": [
     {
      "name": "league",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "nfl",
        "nba",
        "nhl",
        "mlb",
        "wnba",
        "mls",
        "nwsl",
        "pwhl",
        "cfl",
        "epl",
        "laliga",
        "seriea",
        "bundesliga",
        "ligue1",
        "eredivisie",
        "intl",
        "ligamx",
        "ufl",
        "ncaah",
        "afl",
        "nrl"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "belt": {
           "type": "string"
          },
          "generated_at": {
           "type": "string"
          },
          "reigns": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "index": {
              "type": "integer"
             },
             "team": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "reign_no": {
              "type": "integer"
             },
             "start_date": {
              "type": "string",
              "format": "date"
             },
             "end_date": {
              "type": [
               "string",
               "null"
              ],
              "format": "date"
             },
             "days": {
              "type": "integer"
             },
             "defenses": {
              "type": "integer"
             },
             "won_from": {
              "type": [
               "string",
               "null"
              ]
             },
             "won_from_name": {
              "type": [
               "string",
               "null"
              ]
             },
             "opened_by": {
              "type": [
               "integer",
               "null"
              ],
              "description": "belt game number that opened the reign"
             }
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/{league}/api/games.json": {
   "get": {
    "summary": "Every belt game of one belt",
    "parameters": [
     {
      "name": "league",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "nfl",
        "nba",
        "nhl",
        "mlb",
        "wnba",
        "mls",
        "nwsl",
        "pwhl",
        "cfl",
        "epl",
        "laliga",
        "seriea",
        "bundesliga",
        "ligue1",
        "eredivisie",
        "intl",
        "ligamx",
        "ufl",
        "ncaah",
        "afl",
        "nrl"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "belt": {
           "type": "string"
          },
          "generated_at": {
           "type": "string"
          },
          "belt_games": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "n": {
              "type": "integer"
             },
             "date": {
              "type": "string",
              "format": "date"
             },
             "season": {
              "type": "integer"
             },
             "season_type": {
              "type": "string"
             },
             "holder": {
              "type": [
               "string",
               "null"
              ]
             },
             "holder_name": {
              "type": [
               "string",
               "null"
              ]
             },
             "opponent": {
              "type": "string"
             },
             "opponent_name": {
              "type": "string"
             },
             "home": {
              "type": "string"
             },
             "neutral": {
              "type": "boolean"
             },
             "score": {
              "type": "string",
              "description": "home-away"
             },
             "outcome": {
              "type": "string",
              "enum": [
               "established",
               "retained",
               "changed",
               "retained (tie)"
              ]
             },
             "new_holder": {
              "type": "string"
             },
             "new_holder_name": {
              "type": "string"
             },
             "ot": {
              "type": "boolean"
             }
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/{league}/data/reigns.csv": {
   "get": {
    "summary": "Every reign as CSV",
    "parameters": [
     {
      "name": "league",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "nfl",
        "nba",
        "nhl",
        "mlb",
        "wnba",
        "mls",
        "nwsl",
        "pwhl",
        "cfl",
        "epl",
        "laliga",
        "seriea",
        "bundesliga",
        "ligue1",
        "eredivisie",
        "intl",
        "ligamx",
        "ufl",
        "ncaah",
        "afl",
        "nrl"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "text/csv": {}
      }
     }
    }
   }
  },
  "/{league}/data/belt-games.csv": {
   "get": {
    "summary": "Every belt game as CSV",
    "parameters": [
     {
      "name": "league",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "nfl",
        "nba",
        "nhl",
        "mlb",
        "wnba",
        "mls",
        "nwsl",
        "pwhl",
        "cfl",
        "epl",
        "laliga",
        "seriea",
        "bundesliga",
        "ligue1",
        "eredivisie",
        "intl",
        "ligamx",
        "ufl",
        "ncaah",
        "afl",
        "nrl"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "text/csv": {}
      }
     }
    }
   }
  },
  "/all/feed.xml": {
   "get": {
    "summary": "RSS: every title change on every belt",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/rss+xml": {}
      }
     }
    }
   }
  },
  "/all/belt.ics": {
   "get": {
    "summary": "iCalendar: every upcoming belt game on every belt",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "text/calendar": {}
      }
     }
    }
   }
  }
 }
}