{
  "openapi": "3.1.0",
  "info": {
    "title": "ScoreBat Video API",
    "version": "3",
    "description": "Verified against v3 handlers on 2026-11-05. See the Markdown guide for polling, billing, playback and pagination caveats. Example response URLs are illustrative, not live video fixtures."
  },
  "servers": [
    {
      "url": "https://www.scorebat.com/video-api/v3"
    }
  ],
  "security": [
    {
      "ApiToken": []
    }
  ],
  "paths": {
    "/free-feed/": {
      "get": {
        "summary": "Selected older videos; no API credits charged.",
        "description": "Free & paid plan access. No billable API credits.",
        "operationId": "free_feed",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Selected older videos; no API credits charged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatchFeed"
                }
              }
            }
          },
          "403": {
            "description": "Invalid token or insufficient access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found; also an empty league page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly allowance exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/featured-feed/": {
      "get": {
        "summary": "Curated recent and important matches.",
        "description": "Paid plan access. A successful request consumes 5 credits.",
        "operationId": "featured_feed",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Curated recent and important matches.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatchFeed"
                }
              }
            }
          },
          "403": {
            "description": "Invalid token or insufficient access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found; also an empty league page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly allowance exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/team/{slug}/": {
      "get": {
        "summary": "Latest matches with videos for one team.",
        "description": "Paid plan access. A successful request consumes 5 credits.",
        "operationId": "team_bySlug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Look up the exact slug; numeric IDs are not accepted."
          }
        ],
        "responses": {
          "200": {
            "description": "Latest matches with videos for one team.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatchFeed"
                }
              }
            }
          },
          "403": {
            "description": "Invalid token or insufficient access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found; also an empty league page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly allowance exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/team/{slug}/{page}/": {
      "get": {
        "summary": "Latest matches with videos for one team.",
        "description": "Paid plan access. A successful request consumes 5 credits.",
        "operationId": "team_bySlug_page",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Look up the exact slug; numeric IDs are not accepted."
          },
          {
            "name": "page",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Zero-based page. Selects 20 match candidates; output may contain fewer."
          }
        ],
        "responses": {
          "200": {
            "description": "Latest matches with videos for one team.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatchFeed"
                }
              }
            }
          },
          "403": {
            "description": "Invalid token or insufficient access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found; also an empty league page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly allowance exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/competition/{slug}/": {
      "get": {
        "summary": "Latest matches within one competition.",
        "description": "Paid plan access. A successful request consumes 5 credits.",
        "operationId": "competition_bySlug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Look up the exact slug; numeric IDs are not accepted."
          }
        ],
        "responses": {
          "200": {
            "description": "Latest matches within one competition.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatchFeed"
                }
              }
            }
          },
          "403": {
            "description": "Invalid token or insufficient access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found; also an empty league page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly allowance exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/competition/{slug}/{page}/": {
      "get": {
        "summary": "Latest matches within one competition.",
        "description": "Paid plan access. A successful request consumes 5 credits.",
        "operationId": "competition_bySlug_page",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Look up the exact slug; numeric IDs are not accepted."
          },
          {
            "name": "page",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Zero-based page. Selects 20 match candidates; output may contain fewer."
          }
        ],
        "responses": {
          "200": {
            "description": "Latest matches within one competition.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatchFeed"
                }
              }
            }
          },
          "403": {
            "description": "Invalid token or insufficient access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found; also an empty league page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly allowance exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/league/{slug}/": {
      "get": {
        "summary": "Matches across competitions grouped under a league.",
        "description": "Paid plan access. A successful request consumes 5 credits.",
        "operationId": "league_bySlug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Look up the exact slug; numeric IDs are not accepted."
          }
        ],
        "responses": {
          "200": {
            "description": "Matches across competitions grouped under a league.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatchFeed"
                }
              }
            }
          },
          "403": {
            "description": "Invalid token or insufficient access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found; also an empty league page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly allowance exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/league/{slug}/{page}/": {
      "get": {
        "summary": "Matches across competitions grouped under a league.",
        "description": "Paid plan access. A successful request consumes 5 credits.",
        "operationId": "league_bySlug_page",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Look up the exact slug; numeric IDs are not accepted."
          },
          {
            "name": "page",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Zero-based page. Selects 20 match candidates; output may contain fewer."
          }
        ],
        "responses": {
          "200": {
            "description": "Matches across competitions grouped under a league.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatchFeed"
                }
              }
            }
          },
          "403": {
            "description": "Invalid token or insufficient access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found; also an empty league page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly allowance exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/live-streams/": {
      "get": {
        "summary": "Available live-stream / full-match entries, including replays.",
        "description": "Paid plan access. A successful request consumes 5 credits.",
        "operationId": "live_streams",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Available live-stream / full-match entries, including replays.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatchFeed"
                }
              }
            }
          },
          "403": {
            "description": "Invalid token or insufficient access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found; also an empty league page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly allowance exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/updated-endpoints/": {
      "get": {
        "summary": "Teams, competitions and leagues with recent video updates.",
        "description": "Paid plan access. A successful request consumes 5 credits.",
        "operationId": "updated_endpoints",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Teams, competitions and leagues with recent video updates.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Updates"
                }
              }
            }
          },
          "403": {
            "description": "Invalid token or insufficient access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found; also an empty league page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly allowance exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/team/": {
      "get": {
        "summary": "Team directory for programmatic slug lookup.",
        "description": "Paid plan access. A successful request consumes 5 credits.",
        "operationId": "team",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Team directory for programmatic slug lookup.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamDirectory"
                }
              }
            }
          },
          "403": {
            "description": "Invalid token or insufficient access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found; also an empty league page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly allowance exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/competition/{slug}/teamlist/": {
      "get": {
        "summary": "Teams in a competition.",
        "description": "Paid plan access. A successful request consumes 5 credits.",
        "operationId": "competition_bySlug_teamlist",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Look up the exact slug; numeric IDs are not accepted."
          }
        ],
        "responses": {
          "200": {
            "description": "Teams in a competition.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamDirectory"
                }
              }
            }
          },
          "403": {
            "description": "Invalid token or insufficient access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Item not found; also an empty league page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly allowance exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/usage/": {
      "get": {
        "operationId": "usage",
        "summary": "Read your current credit allowance without consuming credits",
        "description": "Uses the normal API token. used = billed API requests × 5 + billable ad-free widget/player loads. Free/inactive accounts have limit 0, not unlimited paid access. See the Markdown reference for reset and cache semantics.",
        "responses": {
          "200": {
            "description": "Free account allowance report; not cached by browser/CDN. Works after exhaustion.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Usage"
                }
              }
            }
          },
          "403": {
            "description": "Invalid token or blocked account/IP",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Unsupported method",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Usage temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiToken": {
        "type": "apiKey",
        "in": "query",
        "name": "token"
      }
    },
    "schemas": {
      "Team": {
        "type": "object",
        "required": [
          "id",
          "name",
          "slug"
        ],
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          }
        }
      },
      "DirectoryTeam": {
        "type": "object",
        "required": [
          "id",
          "name",
          "slug"
        ],
        "properties": {
          "id": {
            "type": [
              "integer",
              "string"
            ]
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          }
        }
      },
      "Video": {
        "type": "object",
        "required": [
          "id",
          "title",
          "embed",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "embed": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Complete ScoreBat player URL, identical to the iframe src in embed. Preserve playback credentials. Playback starts muted; append autoplay=1 to request muted autoplay. Not a direct media file."
          }
        }
      },
      "Match": {
        "type": "object",
        "required": [
          "title",
          "competition",
          "matchviewUrl",
          "competitionUrl",
          "thumbnail",
          "date",
          "homeTeam",
          "awayTeam",
          "videos"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "competition": {
            "type": "string"
          },
          "matchviewUrl": {
            "type": "string"
          },
          "competitionUrl": {
            "type": "string"
          },
          "date": {
            "type": "string"
          },
          "thumbnail": {
            "type": [
              "string",
              "null"
            ]
          },
          "homeTeam": {
            "$ref": "#/components/schemas/Team"
          },
          "awayTeam": {
            "$ref": "#/components/schemas/Team"
          },
          "videos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Video"
            }
          }
        }
      },
      "UpdatedEndpoint": {
        "type": "object",
        "required": [
          "id",
          "entityType",
          "changedAt",
          "endpoint",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "changedAt": {
            "type": "string"
          },
          "endpoint": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "entityType": {
            "type": "string",
            "enum": [
              "team",
              "competition",
              "league"
            ]
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "text"
            ],
            "properties": {
              "code": {
                "type": "integer"
              },
              "text": {
                "type": "string"
              }
            }
          }
        }
      },
      "MatchFeed": {
        "type": "object",
        "required": [
          "response"
        ],
        "properties": {
          "response": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Match"
            }
          },
          "notice": {
            "type": "string"
          }
        }
      },
      "TeamDirectory": {
        "type": "object",
        "required": [
          "response"
        ],
        "properties": {
          "response": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DirectoryTeam"
            }
          }
        }
      },
      "Updates": {
        "type": "object",
        "required": [
          "response",
          "since"
        ],
        "properties": {
          "response": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UpdatedEndpoint"
            }
          },
          "since": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Usage": {
        "type": "object",
        "required": [
          "response"
        ],
        "properties": {
          "response": {
            "type": "object",
            "required": [
              "limit",
              "used",
              "remaining",
              "reset",
              "unit",
              "as_of"
            ],
            "properties": {
              "limit": {
                "type": "integer",
                "minimum": 0
              },
              "used": {
                "type": "integer",
                "minimum": 0
              },
              "remaining": {
                "type": "integer",
                "minimum": 0
              },
              "reset": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "Recorded scheduled reset in UTC, not a promise that a pending renewal has completed."
              },
              "unit": {
                "type": "string",
                "const": "credits"
              },
              "as_of": {
                "type": "string",
                "format": "date-time",
                "description": "Usage snapshot timestamp; may be up to 60 seconds old."
              }
            }
          }
        }
      }
    }
  }
}
