> ## Documentation Index > Fetch the complete documentation index at: https://www.thestatsapi.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For the complete API reference (every endpoint, query parameter and response field), fetch 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 YOUR_API_KEY. Keep the key in server-side code only. # Build with AI (fastest way) > The fastest way to build on TheStatsAPI: give an AI coding tool like Claude Code, Codex, Cursor or Lovable our llms.txt API reference and a starter prompt. 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`](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 [Create an account](https://www.thestatsapi.com/auth?mode=signup), then make a key on the [API keys page](https://www.thestatsapi.com/api-keys). The key is shown only once, so save it straight into a `.env` file in your project: ```bash .env theme={null} THESTATSAPI_API_KEY=YOUR_API_KEY ``` Make sure `.env` is listed in your `.gitignore`. This is the link your AI needs: ```text theme={null} 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: ```bash theme={null} 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. 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. ```text Starter prompt wrap theme={null} 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 . - 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](https://www.thestatsapi.com/build-with-ai) 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. ```markdown Project notes wrap theme={null} ## 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. ``` 1. In your project folder, download the reference (step 2) and create `.env` (step 1). 2. Save the project notes above as `CLAUDE.md` in the project root. 3. Run `claude` and paste the starter prompt. Optional: stop Claude Code from reading your key file. Add this to `.claude/settings.json`: ```json .claude/settings.json theme={null} { "permissions": { "deny": ["Read(./.env)", "Read(./.env.*)"] } } ``` 1. Download the reference (step 2) and create `.env` (step 1) **before** you start Codex. Codex's default sandbox has no network access. 2. Save the project notes above as `AGENTS.md` in the project root. Codex reads it automatically. 3. Run `codex` and paste the starter prompt. 4. When Codex first calls the API, approve the network request. To allow it every time, add this to `~/.codex/config.toml`: ```toml ~/.codex/config.toml theme={null} [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. 1. Download the reference (step 2) and create `.env` (step 1). 2. Save the project notes above as `AGENTS.md` in the project root. Cursor reads it automatically. 3. 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`. 1. Open **Project settings → Knowledge** and paste this (it's always in context): ```text Lovable knowledge wrap theme={null} 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 . 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. ``` 2. Send your first prompt. [Open the starter prompt in Lovable](https://lovable.dev/#prompt=Build%20%5Bdescribe%20your%20app%5D.%20The%20football%20data%20comes%20from%20TheStatsAPI.%0A%0AThe%20full%20API%20reference%20is%20at%20https%3A%2F%2Fapi.thestatsapi.com%2Fllms.txt.%20Read%20it%20first%20and%20only%20use%20the%20endpoints%2C%20query%20parameters%20and%20response%20fields%20listed%20there.%0A%0ACall%20TheStatsAPI%20only%20from%20server-side%20code%20%28a%20server%20function%20or%20Edge%20Function%29%2C%20with%20the%20header%20Authorization%3A%20Bearer%20%3Ckey%3E.%20Store%20my%20API%20key%20as%20a%20secret%20named%20THESTATSAPI_API_KEY%20and%20ask%20me%20for%20it%20with%20the%20secure%20secret%20form.%20Never%20put%20it%20in%20frontend%20code%2C%20.env%20or%20a%20VITE_%20variable.%0A%0AStart%20with%20one%20server%20call%20that%20fetches%20Arsenal%27s%20next%20fixture%20%28GET%20https%3A%2F%2Fapi.thestatsapi.com%2Fapi%2Ffootball%2Fmatches%3Fteam_id%3Dtm_9145%26status%3Dscheduled%26sort%3Dutc_date%26per_page%3D1%29%20and%20show%20it%20on%20the%20page.): it opens with the prompt filled in but not sent, so replace `[describe your app]` first. 3. 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](https://www.thestatsapi.com/api-keys) 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. 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. ```bash theme={null} 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. ```json ~/.cursor/mcp.json theme={null} { "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. ```bash theme={null} 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: ```toml ~/.codex/config.toml theme={null} [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. ```json .vscode/mcp.json theme={null} { "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. ```bash theme={null} 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](https://www.thestatsapi.com/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](/docs/concepts/rate-limits). * **Check coverage before you build a feature.** Not every competition has xG, player stats or odds. See [Coverage](/docs/concepts/coverage). ## More AI resources | Resource | Link | Use it for | | - | - | - | | Full API reference | [api.thestatsapi.com/llms.txt](https://api.thestatsapi.com/llms.txt) | Every endpoint, parameter and response shape. Give this to your AI. | | OpenAPI spec | [api.thestatsapi.com/openapi.json](https://api.thestatsapi.com/openapi.json) | Code generators, Postman and other OpenAPI tools | | Docs index for AI | [thestatsapi.com/docs/llms.txt](https://www.thestatsapi.com/docs/llms.txt) | A list of these docs pages | | All guides as text | [thestatsapi.com/docs/llms-full.txt](https://www.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 Make your first requests by hand and see what comes back. Look up the competition, season, team and player IDs your app needs. What each error code means and how to fix it. Every endpoint, with a playground to try requests. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.