SportLensSign in →

Documentation

Authentication

Send your key as a bearer token. Create one on the API Tokens page (shown once).

curl https://api.sportlens.example/v3/football/competitions \
  -H "Authorization: Bearer sl_live_…"

Every value carries confidence and provenance

The differentiator, baked into the envelope

High92%football_data_orgespn_hidden· majority agreement
{
  "data": { "home_team_id": "…", "home_score": 2, "away_score": 1, "status": "finished" },
  "confidence": { "home_score": 920, "away_score": 880, "status": 1000 },
  "provenance": {
    "home_score": {
      "decided_by": "majority",
      "sources": ["football_data_org", "espn_hidden"],
      "observation_ids": ["…", "…"],
      "is_derived": false,
      "reconciled_at": "2026-06-23T10:00:00.000Z"
    }
  },
  "meta": { "includes": ["home_team"] }
}

Endpoints

GET/v3/football/competitions
List leagues and competitions.
includes: country, seasons
GET/v3/football/competitions/{id}
A single competition.
includes: country, seasons
GET/v3/football/seasons
List seasons.
includes: competition
GET/v3/football/seasons/{id}
A single season.
includes: competition
GET/v3/football/fixtures
List reconciled fixtures.
includes: home_team, away_team, competition, season, venue, events, lineups, stats, broadcasts, odds
GET/v3/football/fixtures/{id}
A single fixture with provenance.
includes: home_team, away_team, competition, season, venue, events, lineups, stats, broadcasts, odds
GET/v3/football/standings
League table for a season (?season_id=).
includes: team, season
GET/v3/football/teams
List teams.
includes: country, venue
GET/v3/football/teams/{id}
A single team.
includes: country, venue
GET/v3/football/players
List players.
includes: country
GET/v3/football/players/{id}
A single player.
includes: country
GET/v3/football/coaches
List coaches.
GET/v3/football/venues
List venues.
includes: country, city
GET/v3/football/venues/{id}
A single venue.
includes: country, city
GET/v3/football/top-scorers
Scorer ranking for a season (?season_id=).
GET/v3/tv/listings
The raw TV guide (any sport), staged from official broadcaster sites — including listings with no fixture yet.
GET/v3/tv/whats-on
The curated feed: live events only, one row per event (deduped across channels), ranked by importance — for a 'where to watch the match' consumer.

Pagination, filtering, errors

  • List endpoints accept ?page and ?per_page (max 100); pagination is echoed in meta.pagination.
  • Filter fixtures by competition_id, season_id, team_id, status, date_from/date_to.
  • Order fixtures with order=asc|desc on kickoff (default desc; an upcoming-schedule reader wants asc with date_from=today).
  • Broadcast-first: has_broadcast_country=RO (ISO alpha-2) keeps only fixtures with a published TV broadcast in that country — pair with include=broadcasts. Each broadcast row carries is_official_source.
  • Incremental sync: updated_since (ISO 8601 instant) returns only fixtures whose row — or any of whose broadcasts — changed since then. Full recipe + caveats in the TV Broadcasts guide.
  • The raw TV guide (any sport, including listings with no fixture yet) is /v3/tv/listings — full recipe in the TV Listings guide.
  • The curated “what to put on the TV” feed (live events only, deduped per event, ranked by importance) is /v3/tv/whats-on — full recipe in the What’s On guide.
  • Errors return a stable { error: { code, message } } shape (e.g. rate_limited, out_of_plan, not_found).