# API-Football

> API-Football (operated by API-Sports) is a REST/JSON API for football (soccer)
> data across 1,200+ leagues and cups worldwide: fixtures, live scores, standings,
> events, line-ups, player and team statistics, transfers, injuries, predictions,
> venues and pre-match/live odds. Live match data is advertised as refreshed every
> 15 seconds. The same account key also reaches the sibling API-Sports products
> for basketball, baseball, hockey, rugby, volleyball, handball, Formula 1 and
> American football.

Generated by API Evangelist on 2026-09-02 from probed evidence and this repository's
artifacts. The provider does not publish an llms.txt of its own
(https://www.api-football.com/llms.txt returns 404), so this file is GENERATED,
not harvested. Every fact below was observed on a live response or read out of
code the provider itself serves; anything unverified is labelled.

## How to call it

- Base URL (direct): `https://v3.football.api-sports.io`
- Base URL (RapidAPI marketplace resale): `https://api-football-v1.p.rapidapi.com/v3`
- Method: GET only. No request bodies anywhere in the public surface.
- Auth (direct): header `x-apisports-key: <your key>`
- Auth (RapidAPI): headers `x-rapidapi-key` + `x-rapidapi-host`
- Keys are issued at https://dashboard.api-football.com/register

## The one thing that will break your integration

A REJECTED KEY RETURNS HTTP 200. Only a request with no key header at all returns
403. Every response — success or failure — has the same shape:

    { "get": ..., "parameters": ..., "errors": ..., "results": N,
      "paging": { "current": 1, "total": 1 }, "response": [ ... ] }

Check `errors` (an object when something went wrong, an empty array when it did
not) BEFORE you trust a 200, then check `results` for the empty-but-valid case.
Do not branch on `response.ok` alone. Also note: the `get` field echoes whatever
path you asked for, including paths that do not exist — it is not a way to
discover the endpoint list.

## Endpoints confirmed live

These were observed being called by the provider's own shipped widget code:

- `GET /fixtures` — matches, filtered by `date`, `league`, `season`
- `GET /standings` — league tables, filtered by `league`, `season`, `team`
- `GET /status` — account/subscription status

The provider documents a much wider surface (countries, leagues, teams, players,
odds, predictions, transfers, injuries, coaches, venues, and fixture sub-resources
for events, line-ups and statistics). That fuller list could not be verified here
and is not enumerated, because the reference is not machine-readable to us — see
"Known gaps" below.

## Pagination, filtering, caching

- Page-number pagination; responses carry `paging.current` and `paging.total`.
- Filtering is flat query parameters (`?league=39&season=2026`). No field
  expansion, no sparse fieldsets, no `include=`.
- The API sets `cache-control: private, no-store, no-cache`, so HTTP caching is
  off by design. Cache client-side to protect your daily quota.

## Rate limits and plans

Metering is a hard DAILY request allowance attached to the API key, reset at
00:00 UTC with no rollover. Published tiers: Free 100/day; Pro $19/mo 7,500/day;
Ultra $29/mo 75,000/day; Mega $39/mo 150,000/day, with plans advertised up to
1,500,000/day. Plans differ by volume and historical depth, not by feature —
every paid plan carries every endpoint and every competition. These figures come
from the provider's pricing page and are recorded `verified: false` because that
page is served to non-browser clients as a Cloudflare managed challenge.

No `RateLimit-*` or `Retry-After` headers appeared on any response we could
observe, so an agent cannot read remaining quota off the wire from an
unauthenticated probe. Budget defensively.

## Widgets

API-Sports ships a first-party browser widget bundle at
`https://widgets.api-sports.io/2.0.3/widgets.js` (ES module). Drop a div with a
reserved id — `wg-api-football-games`, `wg-api-football-game`,
`wg-api-football-standings` — and configure it with `data-key`, `data-host`,
`data-league`, `data-season`, `data-date`, `data-refresh` and friends. Note that
`data-key` puts your API key in client-side HTML. `data-refresh` is ignored below
15 seconds.

## What the provider does NOT ship

- No first-party SDK in any package registry (npm, PyPI) and no public GitHub
  organisation. Every client library on npm is community-authored; the two
  holding the most obvious names were last published in 2020 and 2021.
- No MCP server, no agent card, no ai-plugin.json, no llms.txt.
- No webhooks or streaming/event surface — this is a polling API.
- No status page, no SLA, no published deprecation policy, no `Sunset` headers.
- No security.txt, no vulnerability-disclosure programme, no trust centre.
- No OAuth, no OIDC, no scopes.

## Read-only

Every operation is a GET. There is nothing to reverse, nothing to make
idempotent, and no dry-run to rehearse — account actions such as subscribing or
regenerating a key live in the human dashboard, not in the API.

## Known gaps in this file

API-Football DOES publish an OpenAPI document. Its Redoc documentation page
declares it as `spec-url="public/doc/openapi.yaml"`, resolving to
`https://www.api-football.com/public/doc/openapi.yaml`. That URL, and the whole
of `www.api-football.com`, is served to non-browser clients as a Cloudflare
managed challenge (HTTP 403, `cf-mitigated: challenge`), so the spec could not be
retrieved and is not held in this repository. The endpoint list, parameter
schemas, response models and documented error strings above are therefore
incomplete by exactly that much. This is a retrieval wall on our side, not a
missing contract on the provider's.

## Links

- Website: https://www.api-football.com/
- Documentation (Redoc): https://www.api-football.com/documentation-v3
- OpenAPI (published, challenge-gated): https://www.api-football.com/public/doc/openapi.yaml
- Pricing: https://www.api-football.com/pricing
- Coverage: https://www.api-football.com/coverage
- Widgets: https://www.api-football.com/widgets
- News / announcements: https://www.api-football.com/news/
- Sign up: https://dashboard.api-football.com/register
- Terms: https://www.api-football.com/terms
- Privacy: https://www.api-football.com/privacy
- Corporate (all sports): https://api-sports.io/
- RapidAPI listing: https://rapidapi.com/api-sports/api/api-football