Data Licence API

Base URL & versioning

All endpoints are served under a single versioned prefix. Paths below are relative to it.

https://compwatch.co.uk/api/v1

Authentication

Every request needs a bearer token sent in the Authorization header. Generate a token from the API Data Access section of your account page (available once your licence is active). The token is shown once — store it securely; regenerating revokes the old one.

curl https://compwatch.co.uk/api/v1/competitions \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Accept: application/json"

A valid token without an active licence returns 402; a missing or bad token returns 401.

Tiers & rate limits

Your tier determines which fields and endpoints you can access, and your request budget. Limits are per token.

Exceeding a limit returns 429 Too Many Requests. The value layer = predicted final odds, expected value and cash alternative. The history archive = the per-competition sell-through time-series.

Pagination & formats

List responses are cursor-paginated at up to 200 rows per page. Each response's meta.next_cursor is the cursor for the next page (null on the last page). Pass it back as ?cursor=.

curl "https://compwatch.co.uk/api/v1/competitions?cursor=eyJfcG9pbnRzVG8iO..." \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Responses are JSON by default. Add ?format=csv to the list endpoint for a streamed CSV download (nested objects such as forecast are serialised to JSON within their column).

Endpoints

curl "https://compwatch.co.uk/api/v1/competitions?updated_since=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

curl https://compwatch.co.uk/api/v1/competitions/aB3xY \
  -H "Authorization: Bearer <YOUR_TOKEN>"

curl https://compwatch.co.uk/api/v1/competitions/aB3xY/history \
  -H "Authorization: Bearer <YOUR_TOKEN>"

curl https://compwatch.co.uk/api/v1/sites \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Response schema

Competition object

Returned by /competitions and /competitions/{id}. Base fields are on every tier; the value layer is included only on tiers with value-layer access (Sync and above).

List responses wrap the array in data and carry a meta object:

• tier — the licence tier this response was served under.
• count — number of rows in this page (not the total across all pages).
• next_cursor — cursor for the next page; null on the last page.
• generated_at — ISO 8601 time the response was built.

History object (Intelligence)

{
  "data": {
    "id": "aB3xY",
    "prize": "…",
    "series": [
      { "observed_at": "…", "tickets_sold": 1200, "total_tickets": 5000,
        "price_in_pence": 199, "ends_at": "…" }
    ]
  },
  "meta": { "points": 1, "tier": "intelligence" }
}

series is ordered oldest-first; each entry is one observation we recorded:

• observed_at — when we captured this reading.
• tickets_sold / total_tickets — sold and cap at that moment (cap may be null).
• price_in_pence — ticket price at that moment.
• ends_at — the closing time as it stood then (operators sometimes extend it).

meta.points = the number of observations in series (its length); meta.tier = the tier served.

Site object

Returned by /sites. Fields: slug, name, base_url, company_name, company_founded_year, trust_rating (letter grade only, e.g. "A", "B"), and an indicators object of booleans:

odds_published, transparent_draw, winners_published, free_entry, secure_payments, voluntary_code, player_protection, age_verification, charitable_contributions

Each indicator mirrors a public trust indicator (true = the site meets it). The /sites response isn't paginated; its meta carries count (total sites returned) and generated_at.

Errors

Errors return the appropriate HTTP status with a JSON error message.