Build with AI (fastest way)

Use this page to set up your AI coding tool so it writes code against the real API instead of guessing. It takes about five minutes.

Why this works

https://api.thestatsapi.com/llms.txt is the whole API reference in one Markdown file: every endpoint, parameter and response field. It’s generated from our OpenAPI spec, so it matches the live API.
With it, your AI uses real endpoint and parameter names instead of guessing.
If the AI still sends a wrong parameter, the API answers with 400 UNKNOWN_PARAMETER and suggests the right name, so the AI can fix its own mistake.

Three steps

Get your API key

Create an account, then make a key on the API keys page. The key is shown only once, so save it straight into a .env file in your project:

.env

THESTATSAPI_API_KEY=YOUR_API_KEY

Make sure .env is listed in your .gitignore.

Give your AI the API reference

This is the link your AI needs:

https://api.thestatsapi.com/llms.txt

If your tool works on files in your project (Claude Code, Codex, Cursor), save a copy into the project too:

mkdir -p docs
curl -sL https://api.thestatsapi.com/llms.txt -o docs/thestatsapi-llms.txt

The file is about 300 KB. Web-fetch tools often summarise or cut off long pages, but a local copy can be searched in full. Re-run the curl command now and then to pick up API changes. Don’t add this file to .gitignore: Cursor hides git-ignored files from its AI.

Paste a starter prompt

Replace [describe your app] and paste this into your AI tool. It points the AI at the reference, keeps your key on the server and heads off the most common mistakes.

Starter prompt

I'm building [describe your app] with TheStatsAPI, a football data REST API.

Before you write any code, read the API reference: https://api.thestatsapi.com/llms.txt
If docs/thestatsapi-llms.txt exists in this project, search that copy instead (same file).
Only use endpoints, query parameters and response fields that appear in it. Don't guess.

Rules:
- Base URL: https://api.thestatsapi.com/api. Send the header Authorization: Bearer <key>.
- Read the key from the server-side env var THESTATSAPI_API_KEY. Never put it in browser
  code, in a VITE_ or NEXT_PUBLIC_ variable, or in git. The frontend calls my own server
  route, and only that route calls TheStatsAPI.
- IDs are prefixed strings (comp_, sn_, tm_, pl_, mt_). Look them up with the search
  endpoints, e.g. /football/teams?search=Arsenal&is_mens_team=true. Don't guess IDs.
- Dates use date_from and date_to (YYYY-MM-DD). There is no "date" parameter.
- /football/matches returns newest first. For upcoming fixtures use status=scheduled&sort=utc_date.
- Lists are paginated with page and per_page (max 100 on most endpoints). Read meta.total_pages.
- Errors look like {"error": {"code", "message", "status_code"}}. 400 UNKNOWN_PARAMETER
  means a parameter name is wrong: use the name the message suggests. On 429 (RATE_LIMITED
  or USAGE_LIMIT_EXCEEDED), wait for the number of seconds in the Retry-After header.
- Cache responses. There are no webhooks, so poll live data only as often as the feature needs.
- Check availability flags (has_player_stats, xg_available, shotmap_available, odds_available)
  before calling optional endpoints. History depth varies by competition: check /coverage/leagues.

First, make one test request from the server (Arsenal's next fixture:
/football/matches?team_id=tm_9145&status=scheduled&sort=utc_date&per_page=1) and show me the result.

Want a prompt written for your exact idea? The Build with AI prompt generator in your dashboard asks a few questions about your app, then writes a prompt for Claude Code, Cursor, Lovable or another tool. You need to be logged in.

Set up your tool

For Claude Code, Codex and Cursor, also save these project notes in your project. The AI reads them every session, so it keeps following the rules. Keep the reference file path in backticks and don’t paste the whole llms.txt into this file: it’s too big to load every time.

Project notes

## TheStatsAPI
- API reference: `docs/thestatsapi-llms.txt` (live copy: https://api.thestatsapi.com/llms.txt).
  Search it for the exact endpoint, parameter and field names before writing a call.
  Don't load the whole file at once.
- Base URL https://api.thestatsapi.com/api. Header: `Authorization: Bearer $THESTATSAPI_API_KEY`.
- The key lives in `.env` as THESTATSAPI_API_KEY and is only read by server code.
  Never send it to the browser, log it or commit it.
- Dates: `date_from` / `date_to` (YYYY-MM-DD). There is no `date` parameter.
- Upcoming fixtures: `status=scheduled&sort=utc_date`. `per_page` max 100.
- 400 `UNKNOWN_PARAMETER` = wrong parameter name; the message suggests the right one.
- 429 = wait for `Retry-After` seconds. Cache responses.

Claude Code
Codex
Cursor
Lovable

In your project folder, download the reference (step 2) and create .env (step 1).
Save the project notes above as CLAUDE.md in the project root.
Run claude and paste the starter prompt.

Optional: stop Claude Code from reading your key file. Add this to .claude/settings.json:

.claude/settings.json

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

Download the reference (step 2) and create .env (step 1) before you start Codex. Codex’s default sandbox has no network access.
Save the project notes above as AGENTS.md in the project root. Codex reads it automatically.
Run codex and paste the starter prompt.
When Codex first calls the API, approve the network request. To allow it every time, add this to ~/.codex/config.toml:

~/.codex/config.toml

[sandbox_workspace_write]
network_access = true

Codex Cloud: commit docs/thestatsapi-llms.txt and AGENTS.md so the cloud agent can read them. The agent has no internet access by default: in the environment settings, turn it on and allow api.thestatsapi.com. Codex Cloud removes secrets before the agent runs, so if you want it to make test calls, add THESTATSAPI_API_KEY as an environment variable instead. Use a separate key that you can revoke.

Download the reference (step 2) and create .env (step 1).
Save the project notes above as AGENTS.md in the project root. Cursor reads it automatically.
Open the Agent and paste the starter prompt. You can also mention @docs/thestatsapi-llms.txt in chat to point it at the file.

Cursor hides git-ignored files from its AI. That keeps .env private, but it also means you must not git-ignore docs/thestatsapi-llms.txt.

Open Project settings → Knowledge and paste this (it’s always in context):

Lovable knowledge

This app uses TheStatsAPI (football data REST API).
API reference (every endpoint, parameter and response field): https://api.thestatsapi.com/llms.txt
Only use endpoints, parameters and fields listed there.
Base URL https://api.thestatsapi.com/api. Auth header: Authorization: Bearer <key>.
The key is the secret THESTATSAPI_API_KEY. Only server code (server function or Edge Function)
may call TheStatsAPI. Never put the key in frontend code, .env or a VITE_ variable.
Dates: date_from/date_to (YYYY-MM-DD), no "date" parameter. Upcoming fixtures:
status=scheduled&sort=utc_date. per_page max 100; read meta.total_pages.
400 UNKNOWN_PARAMETER = wrong parameter name. 429 = wait Retry-After. Cache responses.

Send your first prompt. Open the starter prompt in Lovable: it opens with the prompt filled in but not sent, so replace [describe your app] first.
When Lovable asks for your key, enter it in the secure Add secret form, named THESTATSAPI_API_KEY. Don’t type it into the chat.

Lovable secrets are only available to server code (server functions and Edge Functions) and never reach the browser. VITE_ variables do reach the browser, and Lovable commits .env, so never put the key there.

v0, Replit and other app builders: paste the starter prompt and store the key in the tool’s secrets or environment variable settings. Never use a NEXT_PUBLIC_ or VITE_ variable for it: those are bundled into browser code.

Never put your API key in frontend code. The API allows requests from browsers, so an AI tool’s browser-side code will work, but anyone can then copy your key from the page. Keep the key in an environment variable or secret, and call TheStatsAPI only from your own server route. If a key leaks, create a new one on the API keys page and revoke the old one.

Get live data in your AI chat (MCP)

Our MCP server lets your AI assistant look up live football data while you work: find an ID, check today’s fixtures, or see what a response looks like. It doesn’t replace llms.txt for writing code.

Setting	Value
URL	`https://mcp.thestatsapi.com/mcp`
Transport	Streamable HTTP
Auth header	`Authorization: Bearer YOUR_API_KEY`

It uses your own API key, so its calls count against your plan. Its tools are read-only and cover competitions, standings, teams, squads, players, injuries, matches, lineups, match and player stats, shot maps, heatmaps, referees and coverage. It doesn’t include odds; use the REST API for those.

Claude Code
Cursor
Codex
VS Code
Gemini CLI

Export the key first, then add the server. If you don’t export it, the shell expands $THESTATSAPI_API_KEY to nothing and the saved header is empty.

export THESTATSAPI_API_KEY=YOUR_API_KEY
claude mcp add --transport http thestatsapi https://mcp.thestatsapi.com/mcp \
  --header "Authorization: Bearer $THESTATSAPI_API_KEY"

Run claude mcp list to check it shows as connected.

Add this to ~/.cursor/mcp.json. Use this global file, not the project’s .cursor/mcp.json, so your key never ends up in your repo.

~/.cursor/mcp.json

{
  "mcpServers": {
    "thestatsapi": {
      "url": "https://mcp.thestatsapi.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Codex reads the key from an environment variable. Export it in the shell you start Codex from.

export THESTATSAPI_API_KEY=YOUR_API_KEY
codex mcp add thestatsapi --url https://mcp.thestatsapi.com/mcp --bearer-token-env-var THESTATSAPI_API_KEY

This writes the following to ~/.codex/config.toml, which you can also add by hand:

~/.codex/config.toml

[mcp_servers.thestatsapi]
url = "https://mcp.thestatsapi.com/mcp"
bearer_token_env_var = "THESTATSAPI_API_KEY"

Add this to .vscode/mcp.json. VS Code asks for the key once and stores it securely, so the file is safe to commit.

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "thestatsapi-key",
      "description": "TheStatsAPI API key",
      "password": true
    }
  ],
  "servers": {
    "thestatsapi": {
      "type": "http",
      "url": "https://mcp.thestatsapi.com/mcp",
      "headers": { "Authorization": "Bearer ${input:thestatsapi-key}" }
    }
  }
}

-s user saves the server to your user settings, so the key stays out of your project.

gemini mcp add -s user --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  thestatsapi https://mcp.thestatsapi.com/mcp

Windsurf and other clients that support streamable HTTP with a custom header work with the same URL and header. ChatGPT and Claude.ai connectors can’t send an API key yet, so they’re coming soon.

MCP tool arguments are not REST parameters. For example, the find_matches tool accepts date, but the REST endpoint /football/matches only accepts date_from and date_to. When your AI writes code, it should take names from llms.txt, not from the MCP tools.

Prompt ideas

Add one of these after the starter prompt:

Live scores widget: “Show today’s Premier League matches with live scores. Use /football/matches with date_from and date_to set to today, and poll every 60 seconds only while a match is live.”
League table page: “Build a page with the current Premier League table. Get current_season_id from /football/competitions/comp_3039, then call the season’s standings endpoint.”
Fantasy points: “For a finished match, get /football/matches/{match_id}/player-stats and score each player with my rules: 4 points a goal, 3 an assist, 1 for playing 60 minutes or more.”
xG shot map: “Draw a pitch with every shot from /football/matches/{match_id}/shotmap, sized by expected_goals. Only offer it for matches where shotmap_available is true.”
Odds comparison: “For this weekend’s Premier League matches, show the best home, draw and away price across bookmakers from /football/matches/{match_id}/odds. Skip matches where odds_available is false.”

Tips for good results

Paste errors back in. A 400 UNKNOWN_PARAMETER message names the right parameter, for example: Unknown query parameter 'date' (did you mean 'date_from' or 'date_to'?). AI tools can usually fix the call from that.
Give it real IDs. Look them up in the ID finder in your dashboard, or let the AI use the search= endpoints. Don’t let it make IDs up.
Watch your quota. An agent stuck in a retry loop can use up your requests quickly, and trials get 10% of the plan’s limits. Ask for caching. See Rate limits.
Check coverage before you build a feature. Not every competition has xG, player stats or odds. See Coverage.

More AI resources

Resource	Link	Use it for
Full API reference	api.thestatsapi.com/llms.txt	Every endpoint, parameter and response shape. Give this to your AI.
OpenAPI spec	api.thestatsapi.com/openapi.json	Code generators, Postman and other OpenAPI tools
Docs index for AI	thestatsapi.com/docs/llms.txt	A list of these docs pages
All guides as text	thestatsapi.com/docs/llms-full.txt	The text of every docs page in one file
Any docs page as Markdown	Add `.md` to the page URL	Pasting a single guide into a chat
MCP server	`https://mcp.thestatsapi.com/mcp`	Live data inside your AI assistant

Next steps

Quickstart

Make your first requests by hand and see what comes back.

Finding IDs

Look up the competition, season, team and player IDs your app needs.

Errors

What each error code means and how to fix it.

API reference

Every endpoint, with a playground to try requests.

Get started

Guides

Core concepts

Build with AI (fastest way)

Why this works

Three steps

Set up your tool

Get live data in your AI chat (MCP)

Prompt ideas

Tips for good results

More AI resources

Next steps

Quickstart

Finding IDs

Errors

API reference

​Why this works

​Three steps

​Set up your tool

​Get live data in your AI chat (MCP)

​Prompt ideas

​Tips for good results

​More AI resources

​Next steps

Quickstart

Finding IDs

Errors

API reference

Why this works

Three steps

Set up your tool

Get live data in your AI chat (MCP)

Prompt ideas

Tips for good results

More AI resources

Next steps