API-Football

API-Football v3 (API-Sports direct). Auth is a single header x-apisports-key (configured for you from API_FOOTBALL_KEY).

RESPONSE ENVELOPE — every endpoint returns the SAME wrapper: { get, parameters, errors, results, paging: { current, total }, response: [ ... ] }.

• The real data is ALWAYS in response. results is its count.
• IMPORTANT: check errors even on HTTP 200 — an empty array/object means OK; a non-empty errors (e.g. token/plan/parameter problems) means response is empty and the call failed logically.
• Pagination: up to 250 items per page; if paging.total > 1 pass page to fetch more.

SEASONS: season is the 4-digit START year of the season (e.g. 2023 = season 2023/24). DATES: YYYY-MM-DD. Times are UTC unless you pass timezone (get valid values from af_timezone).

TYPICAL FLOW (resolve ids first — do NOT guess numeric ids):

1. af_leagues(search='Bundesliga') → league id (78) + available seasons.
2. af_standings(league=78, season=2023) or af_fixtures(league=78, season=2023, next=10).
3. af_fixtures(...) → a fixture id, then af_fixture_statistics / af_fixture_events / af_fixture_lineups / af_predictions(fixture=id).
4. Teams: af_teams(search=...) → team id; Players: af_players(team=id, season=2023).

RATE LIMIT — the account is on the FREE plan: 100 requests/day (check anytime with af_status, which costs 0). Be economical: use precise filters, prefer a single fixtures/players call with the right filters over many broad calls, and reuse ids you already resolved. Responses expose x-ratelimit-requests-remaining.

Read-only data API: all tools are GET; nothing is written.

=== ANALYSIS === For ANY analysis (preview/prediction, post-match report, team form, head-to-head, standings, top scorers, player scouting, squad, injuries, transfers, odds, live), call af_analysis_playbook FIRST — it returns the exact af_* tool sequence for each case (it makes no API call). HARD RULES: read errors even on HTTP 200 (errors.plan -> season not in plan, tell the user to upgrade); there is NO referee endpoint (referee is only fixture.referee, set late); national-team head-to-head is barely covered; the pre-match odds tool is af_odds_prematch; the players endpoint is paginated (paging.total); never fabricate numbers.

PROFESSIONAL / COMPLETE PREDICTION — when the user wants a 'professional', 'complete' or 'detailed' prediction/analysis, run this FULL checklist in one go and DO NOT stop after the first call:

1. af_teams(search=…)->team id, af_fixtures(team=<id>,next=1)->fixture id + opponent id (+ date, venue, referee).
2. af_predictions(fixture=<id>) — probabilities, advice, comparison, form.
3. af_odds_prematch(fixture=<id>) — bookmaker odds; convert to implied probabilities and COMPARE with the prediction %.
4. af_fixture_lineups(fixture=<id>) — formations & XI (if published).
5. af_team_statistics(league,season,team) AND af_injuries(league,season,team) for BOTH teams.
6. af_topscorers + af_topassists(league,season) AND af_players(team,league,season) — individual player form/ratings.
7. af_head_to_head(h2h='idA-idB') — prior meetings. Only AFTER collecting all of the above do you write the analysis. A one-call (predictions-only) answer is NOT professional — always enrich with odds, lineups, player stats, team stats, injuries and top performers.