API Reference

REST API for live events, schedules, and results. Base URL: https://api.sportsledger.com (use your deployment URL for self-hosted).

Authentication

All API requests (except health) require an API key. Send it via header:

Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY

Get an API key from the dashboard after signing in. Rate limits depend on your tier (Free: 100/min, Pro: 1000/min, Enterprise: 10000/min).

Health

No authentication required.

GET https://api.sportsledger.com/api/health

{
  "ok": true,
  "timestamp": "2026-02-06T12:00:00.000Z"
}

Events

List and fetch sport events (EPL, UFC, Boxing, F1).

List events

GET https://api.sportsledger.com/api/v1/events

Query: sport (optional) — epl, ufc, boxing, f1

[
  {
    "id": "epl-1",
    "sport": "epl",
    "title": "Premier League",
    "subtitle": "Arsenal vs Chelsea",
    "venueName": "Emirates Stadium",
    "venueCity": "London",
    "venueCountry": "England",
    "venueTimezone": "Europe/London",
    "startTime": "2026-02-14T12:30:00.000Z",
    "broadcast": [
      { "platform": "Sky Sports", "region": "UK" }
    ]
  }
]

Get event by ID

GET https://api.sportsledger.com/api/v1/events/:id

{
  "id": "epl-1",
  "sport": "epl",
  "title": "Premier League",
  "subtitle": "Arsenal vs Chelsea",
  "venueName": "Emirates Stadium",
  "venueCity": "London",
  "venueCountry": "England",
  "venueTimezone": "Europe/London",
  "startTime": "2026-02-14T12:30:00.000Z",
  "broadcast": [{ "platform": "Sky Sports", "region": "UK" }]
}

Favourites

Manage a user's favourite events by device ID.

Use a stable deviceId (e.g. from your app) to identify the user.

List favourites

GET https://api.sportsledger.com/api/v1/favourites?deviceId=DEVICE_ID

["epl-1", "ufc-1"]

Add favourite

POST https://api.sportsledger.com/api/v1/favourites

Body: { "deviceId", "eventId" }

{ "success": true }

Remove favourite

DELETE https://api.sportsledger.com/api/v1/favourites/:eventId?deviceId=DEVICE_ID

{ "success": true }

Preferences

Get and update favourite sports and teams per device.

Get preferences

GET https://api.sportsledger.com/api/v1/preferences?deviceId=DEVICE_ID

{
  "favouriteSports": ["epl", "f1"],
  "favouriteTeams": [
    { "sport": "epl", "team": "Arsenal" }
  ]
}

Update preferences

PATCH https://api.sportsledger.com/api/v1/preferences

Body: { "deviceId", "favouriteSports"?, "favouriteTeams"? } — sports: epl, ufc, boxing, f1

{
  "favouriteSports": ["epl", "f1"],
  "favouriteTeams": [{ "sport": "epl", "team": "Arsenal" }]
}

Add favourite sport

POST https://api.sportsledger.com/api/v1/preferences/sports

Body: { "deviceId", "sport" }

Remove favourite sport

DELETE https://api.sportsledger.com/api/v1/preferences/sports/:sport?deviceId=DEVICE_ID

Add favourite team

POST https://api.sportsledger.com/api/v1/preferences/teams

Body: { "deviceId", "sport", "team" }

Clear favourite teams

DELETE https://api.sportsledger.com/api/v1/preferences/teams?deviceId=DEVICE_ID

Errors return JSON with statusCode and message. 401 for missing/invalid API key, 429 when rate limit is exceeded.