API reference overview

What every endpoint has in common. Read this once, then use the endpoint pages for exact parameters and response fields.

Fastest way: give your AI coding tool the full reference. api.thestatsapi.com/llms.txt has every endpoint, parameter and response shape in one Markdown file. Save it in your project:

curl -sL --create-dirs -o docs/thestatsapi-llms.txt https://api.thestatsapi.com/llms.txt

Then ask Claude Code, Codex or Cursor: “Read docs/thestatsapi-llms.txt and build a page that shows Arsenal’s next fixture. Keep my API key on the server.” Setup for each tool, including Lovable: Build with AI.

Base URL

https://api.thestatsapi.com/api

All endpoints are GET and return JSON. The API covers football only.

Authentication

Send your API key in the Authorization header on every request. Get a key at thestatsapi.com/api-keys. Only /health works without one.

curl "https://api.thestatsapi.com/api/football/competitions?search=Premier" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  "https://api.thestatsapi.com/api/football/competitions?search=Premier",
  { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
);
const { data, meta } = await res.json();

import os, requests

res = requests.get(
    "https://api.thestatsapi.com/api/football/competitions",
    params={"search": "Premier"},
    headers={"Authorization": f"Bearer {os.environ['THESTATSAPI_API_KEY']}"},
)
data = res.json()["data"]

Call the API from your server, not the browser, so your key stays private. More in Authentication.

Response format

Paginated lists (competitions, teams, players, matches and coverage by competition) return a data array and a meta object with pagination:

{
  "data": [
    { "id": "comp_3039", "name": "Premier League", "country": "England", "type": "league" }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 11, "total_pages": 1 }
}

Single items return one object in data:

{ "data": { "id": "comp_3039", "name": "Premier League", "current_season_id": "sn_8406098" } }

Short lists such as seasons, standings or a squad come back whole, as a data array with no meta. A few endpoints, such as the shotmap and timelines, add other top-level fields. The examples are shortened; each endpoint page shows the exact shape and every field.

IDs

IDs are strings with a prefix that tells you the type.

Prefix	Type	Example
`comp_`	Competition	`comp_3039` (Premier League)
`sn_`	Season	`sn_8406098` (Premier League 2026/27)
`tm_`	Team	`tm_9145` (Arsenal)
`mt_`	Match	`mt_200199332`
`pl_`	Player	`pl_45126714` (Bukayo Saka)

Look IDs up with the search filter on competitions, teams and players. See Finding IDs and the data model.

Pagination

Paginated endpoints return 20 results per page by default. Set per_page (up to 100) and page, and stop when page reaches meta.total_pages. Coverage by competition is the exception: 100 per page by default, up to 200. See Pagination.

Errors

Every error has the same shape. Branch on code:

{
  "error": {
    "code": "UNKNOWN_PARAMETER",
    "message": "Unknown query parameter 'date' (did you mean 'date_from' or 'date_to'?). Supported parameters: ...",
    "status_code": 400
  }
}

A misspelled or unsupported query parameter returns 400 UNKNOWN_PARAMETER, and the message suggests the right name. A missing or invalid key returns 401 UNAUTHORIZED. All codes are in Errors.

Rate limits

Every authenticated response carries X-RateLimit-* (per minute) and X-Monthly-Quota-* (per billing cycle) headers. Going over returns 429 with a Retry-After header. See Rate limits and pricing.

Machine-readable reference

What	URL
Full API reference for AI tools (Markdown)	api.thestatsapi.com/llms.txt
OpenAPI spec	api.thestatsapi.com/openapi.json
These guides for AI tools	thestatsapi.com/docs/llms-full.txt

Endpoints

Competitions

Competitions, seasons, groups and standings.

Teams

Teams, squads, season stats, standings history, injuries and suspensions.

Matches

Fixtures and results, lineups, timelines, team and player stats, shotmaps, heatmaps and referees.

Players

Player profiles, season stats, injuries and suspensions, and season heatmaps.

Odds

Pre-match, in-play and player-prop odds.

Coverage

Which competitions and seasons have which data.