# Stats API

> A versioned, cache-first REST API for football fixtures, results, competitions, seasons, and teams.

Canonical site: https://stats-api.com
API base URL: https://stats-api.com/v1
OpenAPI 3.1 specification: https://stats-api.com/openapi.json
Human documentation: https://stats-api.com/docs
Coverage: https://stats-api.com/coverage
Launch status: Public documentation preview. API requests and account creation are not open yet.

## Authentication

Send the API key as a Bearer token:

Authorization: Bearer sapi_live_your_key

Never put an API key in a query string or client-side public code. Keys are shown once when created and stored as SHA-256 hashes by Stats API.

## Available endpoints

- GET /v1/health — unauthenticated service health
- GET /v1/coverage/summary
- GET /v1/coverage/leagues
- GET /v1/coverage/leagues/{competition_id}
- GET /v1/football/competitions
- GET /v1/football/competitions/{competition_id}
- GET /v1/football/competitions/{competition_id}/seasons
- GET /v1/football/matches
- GET /v1/football/matches/{match_id}
- GET /v1/football/teams
- GET /v1/football/teams/{team_id}

Collection endpoints accept page and limit. Limit is capped at 100. Match filters are competition_id, season_id, team_id, status, date_from, and date_to. Team and competition collections accept q where documented.

## Contract and freshness

Public IDs are stable Stats API IDs and do not expose an upstream provider's identifiers. Customer requests read Redis and normalized MySQL data; they never call an upstream provider directly. Responses include X-Request-ID, X-StatsAPI-Cache, rate-limit, and monthly-quota headers. Each authenticated request counts toward quota, including cache hits and errors after authentication.

Only fields and endpoints present in the OpenAPI specification are production contract. Planned player, standings, live-score, lineup, odds, and prediction endpoints must not be assumed available.

## Response shape

Successful item:
{"data": {...}}

Successful collection:
{"data": [...], "meta": {"page": 1, "limit": 25, "request_id": "..."}}

Error:
{"error": {"code": "machine_readable_code", "message": "Human-readable message", "details": {}}}

## Safe integration prompt

Read https://stats-api.com/openapi.json first. Generate a server-side client that uses an API key from the STATS_API_KEY environment variable, sets the Authorization Bearer header, handles 401/429/503 responses, honors rate-limit headers, and uses only operations marked available in the specification. Do not invent fields or planned endpoints.