API v1 retired: v2 catalogues, fixture redirects, change feeds and source health

New

• Reference catalogues (live). /api/v2/sports, /api/v2/countries and /api/v2/competitions return plain lists ordered by name, then id. They need no market. /competitions takes sport_ids and country_ids (repeat the parameter; up to 100 IDs each). IDs in one filter combine with OR, the two filters with AND. Unknown parameters answer 422. Competitions carry country_id; look the name up in /countries.
• Redirects for merged fixtures (live). When two fixtures turn out to be one, the retired fixture ID now answers 410 Gone instead of 404. The body names the surviving fixture in superseded_by, and a Link header with rel="successor-version" points to it. This applies to /api/v2/matches/{id} and its /availability and /schedule-evidence reads. Hidden and unknown IDs still answer 404.
• Merges feed (live). GET /api/v2/fixtures/merges?since=0 lists merges oldest first, so you can update stored IDs without waiting for a request to fail. since is a feed position, not a time. Pass next_since back until it is null. limit is 1–1000 (default 500).
• Channel changes feed (live; currently empty). GET /api/v2/channels/changes?since=… lists changes to the channel catalogue: splits, merges, renames and market moves. since is an instant with an explicit offset. No change has been published to the feed yet, so it answers with an empty changes list.
• Source health (live). GET /api/v2/source-health?market=GB reports, per registered broadcast feed in a market, when its latest accepted import completed and how that import ended. An import is not independent verification of any listing. Fields, outcomes and the five events it does and does not describe are on the source health page.

curl --get 'https://worldsportsapi.com/api/v2/competitions' \
  -H "x-api-key: $SPORT_API_KEY" \
  --data-urlencode 'sport_ids=1'

curl --get 'https://worldsportsapi.com/api/v2/fixtures/merges' \
  -H "x-api-key: $SPORT_API_KEY" \
  --data-urlencode 'since=0' \
  --data-urlencode 'limit=500'

{
  "error": "fixture_merged",
  "detail": "Fixture 45 was merged into fixture 123",
  "superseded_by": 123,
  "merged_at": "2026-10-07T21:27:03.066505+00:00"
}

Changed

• Placeholder channels and broadcasters are hidden by default. /api/v2/channels and /api/v2/broadcasters leave out stand-ins such as TBC (is_placeholder is true) unless you add include_placeholders=true. The value must be exactly true or false; anything else answers 422. Today three rows are affected: channels 961 TBC and 2274 TNT Sports TBC, and broadcaster 33 TBC. Channel 33 is a separate, real channel and is not hidden. Fixture listings are unchanged: a listing on a placeholder channel still appears in /matches, and a placeholder ID is still accepted as channel_id.
• The API schema. The OpenAPI document no longer lists any /api/v1 read path, documents the 410 response and the new endpoints, and names the channel schema Channel. If you generate a client, regenerate it.
• The documentation is v2 only. The quickstart, examples and reference describe v2. See the global contract for markets, timezones, feeds and redirects.

Breaking: public v1 read endpoints are retired

The public API no longer serves the v1 read endpoints below and answers 404 Not Found. A request answered by the Sport API website gateway instead returns 410 Gone with a JSON body containing replacement: the v2 path, or null where v2 has none. Treat both as the signal to move.

Four of these have no v2 equivalent: competitions/stages, competitions/aliases, participants and broadcasters/channels/aliases. Still available under /api/v1: the root, /api/v1/readyz, and the /api/v1/openapi.json redirect to /api/openapi.json.

Fixes

• Source health could fail with a server error. The first deployment of /api/v2/source-health on 14 October did not give the API’s read-only role access to the freshness columns it reads, so a request could answer 500. The access is now granted, for those columns only, and the endpoint answers 200 for GB and IE.

Required migration steps

1. Search your code and logs for requests to /api/v1/. Each one now fails.
2. Replace each with its v2 path from the table above. The migration guide lists what changes in each.
3. For fixtures, send civil start_date and end_date with an IANA timezone, or offset-bearing from and to. Send market to receive broadcast listings. Read fixtures from items.
4. For channels and broadcasters, send market. Add include_placeholders=true only if you relied on rows such as TBC.
5. For competitions, read country_id and look the name up in /countries. Drop the name and country filters, and use sport_ids instead.
6. Handle 410 when you read a fixture by ID. Store superseded_by in place of the old ID, and poll /fixtures/merges to update stored IDs ahead of time.
7. If you store channel IDs, poll /channels/changes and re-key what you stored for the market named in each change.
8. Regenerate any client built from the OpenAPI document.

Notice before a breaking removal

From 14 October 2026, a breaking removal will be announced in these release notes at least 90 days before it takes effect. The announcement will name the replacement and removal date. Additive changes need no notice. A shorter period is allowed only when a law, a security problem or a source licence forces it; the announcement will explain why. This policy does not change past retirements.

What is live and what is not enabled