Migrate from v1 · API documentation

Move from v1 to v2.

The public v1 read endpoints were retired on 14 October 2026. Your API key, allowed origins and allowance work with v2 unchanged. See the release note for everything that shipped with it.

What a retired request returns

The public API answers 404 Not Found for the paths below. A request answered by the Sport API website gateway instead returns 410 Gone with {"error": "...", "replacement": "/api/v2/..."}, where replacement is null if v2 has no equivalent. Neither returns data. The OpenAPI document lists no v1 read path.

Each retired path and its replacement

Retired v1 read paths and their v2 replacements
v1 path (retired)	v2 replacement	What changes
`/api/v1/sports`	`/api/v2/sports`	Same list: id, name, slug. v2 omits description, which was always null.
`/api/v1/countries`	`/api/v2/countries`	Same list: id, name, iso_code, fifa_code. v2 omits source and verified.
`/api/v1/competitions`	`/api/v2/competitions`	Returns country_id, not a country name: look the name up in /countries. The name and country filters are gone; sport_ids is new and country_ids is kept.
`/api/v1/competitions/stages`	No v2 equivalent	No v2 equivalent. A fixture’s stage arrives on /matches as stage: { id, name }.
`/api/v1/competitions/aliases`	No v2 equivalent	No v2 equivalent.
`/api/v1/participants`	No v2 equivalent	No v2 equivalent. Fixtures carry home_team and away_team as { id, name }.
`/api/v1/matches`	`/api/v2/matches`	Pass civil start_date and end_date with timezone, or offset-bearing from and to. Add market for broadcasts. v1 country_ids has no single v2 equivalent: choose team_country_ids, venue_country_ids or competition_country_ids. The response is a page: read items.
`/api/v1/matches/next`	`/api/v2/matches/next`	Requires start_date and timezone.
`/api/v1/matches/source-status`	`/api/v2/matches/source-status`	Requires market. In v2 this path is an alias of /coverage; it reports coverage windows, not import health. Use /source-health for import health.
`/api/v1/matches/{match_id}`	`/api/v2/matches/{match_id}`	Requires timezone; market is optional. A merged fixture answers 410 with superseded_by.
`/api/v1/broadcasters`	`/api/v2/broadcasters`	Requires market. The name and broadcaster_id filters are gone. Placeholders are hidden unless include_placeholders=true.
`/api/v1/broadcasters/channels`	`/api/v2/channels`	Now /channels. Requires market. The broadcaster_id and name filters are gone. Placeholders are hidden unless include_placeholders=true.
`/api/v1/broadcasters/channels/aliases`	No v2 equivalent	No v2 equivalent.
`/api/v1/participants/resolve`	No v2 equivalent	Teams are identified by id on every fixture (home_team and away_team).

Four paths have no v2 equivalent: competitions/stages, competitions/aliases, participants and broadcasters/channels/aliases.

Fixtures: dates, timezones and markets

v1 returned London dates and times. v2 returns a UTC starts_at and a display object in the timezone you ask for, and you choose the broadcast market separately. Civil dates require timezone; alternatively send from and to with explicit offsets. Read fixtures from items and page with next_cursor. The global contract has the full rules.

GET /api/v2/matches?start_date=2026-10-05&end_date=2026-10-05&market=GB&timezone=America%2FNew_York
x-api-key: fg_YOUR_SECRET_KEY

curl --get 'https://worldsportsapi.com/api/v2/matches' \
  -H "x-api-key: $SPORT_API_KEY" \
  --data-urlencode 'start_date=2026-10-05' \
  --data-urlencode 'end_date=2026-10-05' \
  --data-urlencode 'market=GB' \
  --data-urlencode 'timezone=America/New_York'

Catalogues

Competitions carry country_id, not a country name. Read /countries once and join on id. Filter competitions with sport_ids and country_ids.

GET /api/v2/competitions?sport_ids=1
x-api-key: fg_YOUR_SECRET_KEY

GET /api/v2/countries
x-api-key: fg_YOUR_SECRET_KEY

[
  {
    "id": 18,
    "name": "Premier League",
    "slug": "football-england-premier-league",
    "sport_id": 1,
    "country_id": 2,
    "gender": "men"
  }
]

/channels and /broadcasters need market and hide placeholders such as TBC unless you send include_placeholders=true.

GET /api/v2/channels?market=GB&include_placeholders=true
x-api-key: fg_YOUR_SECRET_KEY

Stored fixture and channel IDs

A fixture ID is stable until the fixture is merged into another. A merged ID answers 410 Gone with superseded_by, and /fixtures/merges lists every merge so you can update stored IDs. If you store channel IDs, /channels/changes lists catalogue changes to re-key. Both are described in the global contract.

GET /api/v2/fixtures/merges?since=0&limit=500
x-api-key: fg_YOUR_SECRET_KEY