Odds HTTP API reference

Base URL and authentication

Direct keys call https://api.arbplay.app with the header X-API-Key: YOUR_API_KEY. A key normally belongs to one bookmaker (its company key) and reads only that bookmaker's files; a direct key can also cover several bookmakers or a chosen set of files, and then company carries that bundle's name.

Marketplace subscribers call the marketplace's gateway instead, with the marketplace's own key. The endpoints and responses are the same:

Keep keys server-side: the API sends no CORS headers, so browser calls fail by design.

GET /v1/files

Lists the files your key can read, sorted by name. Only files that exist right now are listed.

{
  "company": "stoiximan",
  "count": 5,
  "files": [
    "site_live_stoiximan.json",
    "site_pregame_stoiximan_basketball.json",
    "site_pregame_stoiximan_soccer.json",
    "site_pregame_stoiximan_soccer_leagues.json",
    "site_pregame_stoiximan_tennis.json"
  ]
}

GET /v1/data/{filename}

Returns one file inside a four-key envelope, always in this order:

{
  "company": "bwin",
  "file": "site_pregame_bwin_soccer.json",
  "updated_at": "2026-09-26T20:02:24Z",
  "data": {
    "fixtures": [
      "… Bwin's own JSON, unchanged …"
    ]
  }
}

The file is streamed from disk as-is — never parsed or re-serialized — so data is exactly what the scraper wrote. Files are replaced atomically, so a response is always one complete version of the file. Response headers: Content-Length, Last-Modified and Cache-Control: no-cache. See each bookmaker page for the structure inside data, or download a real sample.

Conditional requests (304)

Send the last Last-Modified value back as If-Modified-Since. Until the file is rewritten the API answers 304 Not Modified with no body. An invalid or future date is ignored. updated_at and Last-Modified have one-second resolution, and a 304 still counts toward your rate limit.

curl -sS -o /dev/null -w "%{http_code}\n" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "If-Modified-Since: Sat, 26 Sep 2026 20:02:34 GMT" \
  https://api.arbplay.app/v1/data/site_live_stoiximan.json
# 304 until the file is rewritten, then 200 with the new body

Compression

Send Accept-Encoding: gzip (curl --compressed; Python requests and Node fetch do it for you). Responses arrive about 6–7 times smaller (Fonbet's 8.6 MB file comes down as about 1.2 MB), which matters most for the largest files: Superbet pre-match soccer is around 200 MB uncompressed and Bwin pre-match soccer around 10 MB.

Errors

Every error body is {"detail": "<message>"}. Checks run in this order and the first failure wins — note that an unknown filename is 403, not 404.

Rate limits

• Limits are counted per key and per path: each filename is its own bucket, and /v1/files is another.
• Marketplace traffic is limited to 10 requests per second per path at the origin; your plan's monthly quota is enforced by the marketplace.
• A 429 carries Retry-After (seconds). Polling with If-Modified-Since at the file's refresh rate is the efficient pattern.
• What counts as a request, and how to size a plan: Odds API FAQ.

Freshness

• Live files are rewritten about every 1–3 s and pre-match files about every 4–7 s during active hours.

File catalogue

All 34 files. Each key reads the files of its own bookmaker, or of its bundle; GET /v1/files returns the current list.

Code examples

Poll one file with If-Modified-Since (Python)

import time
import requests

URL = "https://api.arbplay.app/v1/data/site_live_novibet.json"
session = requests.Session()
session.headers["X-API-Key"] = "YOUR_API_KEY"
last_modified = None

while True:
    headers = {"If-Modified-Since": last_modified} if last_modified else {}
    resp = session.get(URL, headers=headers, timeout=60)
    if resp.status_code == 200:
        last_modified = resp.headers["Last-Modified"]
        payload = resp.json()  # {company, file, updated_at, data}
        print("file updated", payload["updated_at"])
    elif resp.status_code == 429:
        time.sleep(int(resp.headers.get("Retry-After", "1")))
        continue
    elif resp.status_code != 304:
        resp.raise_for_status()
    time.sleep(2)

List and download every file (Node 18+)

// Node 18+, server-side (no CORS)
const BASE = "https://api.arbplay.app";
const headers = { "X-API-Key": process.env.ARBPLAY_API_KEY };

const { files } = await (await fetch(`${BASE}/v1/files`, { headers })).json();
for (const file of files) {
  const res = await fetch(`${BASE}/v1/data/${file}`, { headers });
  if (!res.ok) { console.error(file, res.status, (await res.json()).detail); continue; }
  const { updated_at, data } = await res.json();
  console.log(file, updated_at);
}

Per-bookmaker parsers for match-result odds are on each bookmaker page.

Samples, OpenAPI and Postman

• OpenAPI 3.1 spec — envelope schemas, every error, headers and examples
• Postman collection — set apiKey and run
• Real samples — one or more per bookmaker, in the exact response format
• /llms.txt — a plain-text summary for AI assistants

Frequently asked questions

Bookmaker pages: Stoiximan · Novibet · Fonbet · Superbet · Elabet · OPAP (Allwyn) · Bwin.
api.arbplay.app is the Odds HTTP API. It is separate from the ArbPlay app's own endpoints under arbplay.app/api/* (sign-in, the arbitrage feed), which are not a public API.