One API.
One schema.

Quickstart.

Three lines.

That returns Granit Xhaka's profile JSON — biographics plus available external_ids cross-references. The same filtering and embedding pattern works across the documented resources. No SDK is required.

Authentication.

Reads authenticate with your x-api-key header (keys look like fio_live_… and are issued at /signup). Keys are stored only as SHA-256 hashes — shown once at creation, never re-shown.

The public project key also permits an unsupported browser-preview path. Database RLS limits season- and match-scoped canonical rows on that path—and on issued free keys—to the current season of competitions on the free list: 196 competitions served at least one current-season match when we measured on 6 August 2026. Historical access requires a valid key assigned basic, pro or enterprise; MCP tool queries use the same database rule, and every tier reads through the same licence gate. Public catalogue and aggregate coverage views can remain broader so gaps are inspectable without implying raw historical entitlement.

Closed-beta quotas and content tiers are assigned per invite; the pricing matrices described elsewhere are not currently self-serve purchasable plans. Per-minute and monthly allowances are plan terms enforced atomically on the metered gateway (below) and on MCP tool calls. Direct PostgREST reads are not usage-metered today — no X-RateLimit-* headers and no 429s on that surface. Lost or leaked keys are rotated by emailing hello@foot.io.

Metered gateway.

Keyed requests can also go through the metered gateway, which enforces per-minute and monthly limits atomically and returns your remaining allowance on every response. Same PostgREST query syntax, same tier entitlements; only the base URL changes:

The gateway is read-only (GET/HEAD) and does not expose RPC endpoints. Direct PostgREST access keeps working during the beta; new integrations should prefer the gateway — usage-based plans will bill from its meters. Your key's per-minute and monthly allowances are set by your plan — see pricing for the current limits.

Filtering.

Operators on selectable columns in documented resources, using standard PostgREST syntax. Machine-readable spec: openapi-v2.yaml.

Embedding.

Pull related rows in one request.

One round-trip. Embedding follows foreign keys. The alias syntax (home:teams!matches_home_team_id_fkey) is required where a table has multiple FKs to the same target (matches→teams, match_events→players) — a bare embed errors with PGRST201.

Pagination & limits.

Either ?limit=50&offset=100 or HTTP Range header (Range: 0-99). There is no 100-row default page: a query without limit returns up to the server's hard cap of 1,000 rows, and a larger limit is clamped back to 1,000 (measured 6 Aug 2026). Use Prefer: count=exact to get the total count in the Content-Range header.

Players.

311,637 indexed profiles in one schema (measured 10 Aug 2026). Field completeness varies; handle nulls.

The licence gate.

Every tier — Enterprise included — reads only rows we hold an explicit right to redistribute. That is the single biggest gap between what we hold and what a key reads, so here it is in numbers, all measured on 10 August 2026: we hold 1,177,209 matches; every tier reads 733,863 of them (62.3%). We hold 2,302,414 match events; 42.9% pass the gate. We hold 7,459,954 lineup rows; 32.9% pass. Of the 926 competitions with recorded matches, 763 serve at least one match and 163 currently serve zero.

Not served at any tier: transfers (we hold 159,823 rows; zero pass the gate), shot-level data including every xG field, and top-5-league events and lineups. Standings do pass: we hold 58,637 standings rows and 55,391 of them (94.5%) are served (measured 6 Aug 2026). Withdrawn entirely on 28 July 2026: player market values and injuries. Historical odds are served to paid tiers — 6,222,372 quotes across 130,550 matches in 21 competitions — but only 49,929 of those matches (38.2%) currently join to a result row the gate serves.

What the gate does not do is discriminate between paid tiers: there is no competition gating between them, and the cheapest paid key reads exactly the same rows as the most expensive one. Tiers differ in rate, quota and historical depth — free reads the current season across the 196-competition free list; paid tiers read full history — never in which rows pass the gate. If an endpoint looks thinner than the totals we publish for what we hold, this section is why. The defensible share grows as licensing lands; the figures above are the served surface today, not a ceiling.

stat_scope — read this before ranking anyone.

Every player_season_stats row carries stat_scope, which says what the numbers count:

Both scopes are correct — they answer different questions. But if you order=goals.desc without pinning the scope, your "top scorer" list mixes them and is wrong. Always:

Rows also carry source (fbref, api-football, stathead, …). The same player-season can legitimately appear once per source; dedupe by picking a source or aggregating deliberately.

Provenance & confidence.

Many canonical fact rows carry a source column naming the pipeline that wrote them, but legacy and entity-level provenance is not yet complete. Current cross-source tier views classify matches and player-season rows (see methodology):

n_sources is the assessed independent-publisher count; raw_source_count, independence_groups, provenance notes and unassessed namespaces preserve the audit trail. Open cross-source contradictions feed source_disagreements-backed tiers. These are row-level classifications, not proof of every field; a flagged row is your cue to compare sources rather than quote a single number.

Field-level entity facts use /entity_fact_verification. Filter by subject_type and subject_id; the response labels each assertion single_source, multi_source_unverified, corroborated or conflict and retains candidate_values. Corroborated means agreement across at least two assessed publisher-independence groups. sources_agreeing, source_count_status and unassessed_sources keep the raw labels visible without overstating them. /entity_facts_resolved fails closed: it returns every verified member of a multi-value predicate, but no guessed value for a scalar conflict.

Match-event corroboration uses /match_event_verification. It returns one row per canonical event with observation_count, source_count, contributing sources, verification_status and any fail-closed field_conflicts. Raw source payloads are retained privately rather than duplicated in canonical event results.

Assist semantics are versioned at /assist_definitions. A publisher-reported assist, a potential assist (a chance-creating action whether or not the shot is scored) and a rule-derived key-pass candidate are different concepts. Candidate assertions do not become publisher facts, and models, rules or multiple workers in one managed annotation pipeline never count as independent corroborating publishers. The assertion and evidence tables remain private while licensing and editorial review are incomplete.

Use /entity_fact_provenance for assertion-level evidence. It exposes the registered source, exact import run when available, stable source record/page identifier, retrieval timestamp and optional SHA-256 digest. provenance_status is deliberately explicit: run_and_record, source_record, import_run_only, source_only, unregistered_source or invalid_subject. Historical facts are not upgraded to stronger labels without evidence.

/entity_fact_provenance_gap_summary groups every assertion still lacking record-level evidence by status, subject type, predicate and source. Missing canonical subjects or referenced objects are not served as facts: their full pre-images are retained internally, while /entity_fact_integrity_summary publishes the safe aggregate and the database rejects new dangling references.

/source_entity_identities maps a registered publisher record ID to one canonical entity with a uniqueness and target-existence gate. /ingestion_gate_totals reports raw staging and unresolved-quarantine states without exposing source payloads. Staging promotion is service-only and fail-closed: name-only auto-creation is retired, while identity, evidence, source/import consistency and match-result conflicts are rechecked inside the transaction.

Historical completeness uses an explicit denominator. /competition_completeness includes every public competition—even unresearched ones—while /expected_competition_seasons expands researched targets into each expected year and labels it present, missing_season, empty_season, scoreless_season, duplicate_seasons or an evidence-backed exception such as not_held. Only verified_complete=true is a completeness claim.

The measured gaps are executable queues. /competition_research_queue ranks every unresearched competition by indexed-match impact and identifies the next evidence task; last_research_method, last_research_outcome, last_researched_at and research_retry_after preserve the latest exact-identity or exact-Wikipedia-page attempt instead of repeatedly discarding failed research. Automated contracts remain provisional and require source-backed inception plus either an explicit end or stored-season evidence; a missing dissolution date does not establish current activity. Wikipedia evidence cites an immutable article revision. Inception metadata alone is a lead, never a contract. /coverage_gap_remediation_queue expands every missing or impaired contract year, routes it to an existing ingestion or integrity-repair lane, and exposes the latest exact publisher/year outcome. source_unavailable remains a measured gap and means the next acquisition must use another publisher until the recorded retry date.

Exact fixture-count completeness has a second denominator. /competition_season_fixture_contract_queue contains every stored public competition-season, not only researched rows, and labels seasons without a cited expected count unresearched. /competition_season_fixture_contract_summary provides corpus-wide totals; source-contracted rows expose stored, orientation-independent distinct, played and scoreless counts separately.

Competition labels have their own evidence contract. /competition_classification_completeness separates missing canonical values, missing evidence and source conflicts for format, gender, age group, scope, country, tier and lineage. /competition_classification_summary and /competition_classification_gap_summary provide corpus-wide aggregates without API-page truncation. Treat only classification_status=verified as fully evidenced.

/match_source_acquisition_summary keeps the full single-source denominator intact while splitting the next run into actionable_* and deferred_* totals. verified_assertion_count includes exact same-publisher provenance recovered by stable-ID re-emitters; verified_match_count counts only matches whose assertion publisher group differs from the canonical match source group. Deferred means a specific publisher/season attempt is unsupported or unresolved until its retry date; it does not mean the match is verified or removed from the backlog.

MCP server.

The MCP server is a deployed stateless HTTP JSON-RPC endpoint. Discovery is available; tool execution is invite-only and output quality follows the same coverage and provenance caveats as REST.

31 question-shaped tools — search/detail for players, teams, matches; standings, top scorers, head-to-head, form, fixtures, honours, scope-aware season stats, current squads, the newspaper archive, Wikidata claims, and the same quality contracts served over REST. The transfers tool remains deployed but currently returns no rows: no transfer rows pass the licence gate at any tier. get_data_quality_summary, get_competition_coverage and get_fact_evidence expose unresearched denominators, publisher-aware tiers, conflicts, provenance and quarantine states to agents instead of returning data without its caveats. Account-less pay-per-call access over the x402 protocol is built and in testnet validation.

Webhooks (roadmap — not yet available).

Planned: POSTs to your endpoint on transfer.completed, match.finished, goal.scored and similar. Not yet shipped — today, poll the REST surface (a matches?status=eq.live query is cheap) or ask hello@foot.io to be notified when webhooks land.

Are we the right API for you?

Often not, and it is cheaper for both of us if you work that out now. We have written the comparisons ourselves and named the places each competitor beats us — live latency, licensed depth, price, and years of proven reliability are all rows where somebody else wins:

• foot.io vs API-Football — the live-data comparison. If your product shows in-play scores, buy theirs: their cycle is around 15 seconds and ours is five minutes.
• foot.io vs Sportmonks — the licensing comparison. League-scoped plans with contractual depth and redistribution rights we do not currently have.
• foot.io vs football-data.org — the free-tier comparison. If your project fits inside their 12 free competitions, keep using them.

The reasons to use us instead are narrow and specific: history back to 1871, no competition gating on any paid key, 6.2M pre-match odds quotes served to paid tiers on our match id (though only 38.2% of odds matches currently join to a served result row — measured 10 Aug 2026), free unmetered cross-provider ID resolution via resolve_entity, and the MCP server above. Every coverage number on those pages is served from the public competition_season_coverage endpoint, so you can falsify them without a key — please do.