One key, one base URL, three delivery shapes

# 1 — health (no key required; it does not check one)
curl -s "https://api.foreline.io/v1/health"

{ "status": "ok", "version": "foreline-gw/1.0", "ts": 1785450885.03,
  "registry": { "readable": true }, "data": { "warm": true, … } }

# 2 — one event, full ladder
curl -s "https://api.foreline.io/v1/surface?event_id=1632432003" \
  -H "X-Foreline-Key: $FORELINE_KEY"

# 3 — bulk delta from the start, then repeat with the returned next_cursor
curl -s "https://api.foreline.io/v1/surface?since=0&limit=200" \
  -H "X-Foreline-Key: $FORELINE_KEY"

{ "events": [ … ], "more": true,
  "next_cursor": "1785433471.4442058:1632973256", "next_since": 1785433471.4442058, … }

# 4 — the next page: next_cursor goes back in `since`, verbatim.
#     Loop on `more`, never on the row count, and never on next_since.
curl -s "https://api.foreline.io/v1/surface?since=1785433471.4442058:1632973256&limit=200" \
  -H "X-Foreline-Key: $FORELINE_KEY"

The same three calls as a script you can run

Python 3.7+ and the standard library — no SDK, no pip install, no OAuth. Paste your key on the second line and run it. It prints what your key carries, picks a match from the catalog and prints that match's whole ladder.

import json, urllib.request, urllib.error

KEY  = "PASTE-YOUR-KEY-HERE"
BASE = "https://api.foreline.io"

def get(path, key=KEY):
    req = urllib.request.Request(BASE + path, headers={"X-Foreline-Key": key})
    try:
        with urllib.request.urlopen(req, timeout=30) as r:
            return json.load(r)
    except urllib.error.HTTPError as e:
        body = json.load(e)                      # every error body is JSON
        raise SystemExit("HTTP %s on %s\n  %s\n  %s" % (
            e.code, path, body.get("error"), body.get("hint", "")))

# 1. Is the service up? The cheapest call in the API — it needs no key.
h = get("/v1/health", key="")["data"]
print("service ok, %s events in memory, last tick %.0fs ago"
      % (h["events"], h["last_tick_age_s"]))

# 2. What does your key carry? Products, sports, history depth, limits.
u = get("/v1/usage")
print("products: %s | sports: %s | history: %s | cadence: %ss"
      % (", ".join(u["scopes"]), ", ".join(u["sports"]),
         u["asof_days"] or "unlimited", u["data_cadence_s"]))

# 3. Which matches can you ask about? Always address events by OUR event_id.
ev = get("/v1/catalog/events?hours=24&limit=3")["events"]
for e in ev:
    print("%s  %s vs %s  (%s)"
          % (e["event_id"], e["home"], e["away"], e["league"]))

# 4. The product: the whole ladder for one match — the rungs the reference
#    market quotes AND the rungs it does not.
s = get("/v1/surface?event_id=%s" % ev[0]["event_id"])
for name in ("spread", "totals"):
    m = s["markets"].get(name)
    if m is None:
        continue          # a market the reference is not quoting right now
    print("\n%s: main line %s, fair %s, vig tier %s"
          % (name, m["main_line"], m["fair_market"], m["vig_tier"]))
    for r in m["rungs"][:5]:
        p = r["p_home"] if name == "spread" else r["p_over"]
        band = r["band_pp"]
        print("  line %-6s p %-8s band %-14s %s"
              % (r["line"], p,
                 "n/a" if band is None else "%+.2f..%+.2f" % tuple(band),
                 r["src"]))

print("\n'quote' = the reference market quotes that rung.")
print("'table' = we reconstruct it, and the band widens to say so.")

Values in examples throughout the docs come from real responses and will not match yours. next_since in that envelope is a legacy epoch boundary, not a paging cursor — see Cursors & paging for what it costs to loop on it.

• Header: X-Foreline-Key: <your key> on every request, including the SSE stream. There is no OAuth dance and no token exchange.
• Transport: HTTPS only. Requests without the header, or with a key that has been revoked, return 401.
• Scope: a key carries the products, sports and history depth in your contract. A call to something outside that scope returns 403 rather than an empty result — you always know the difference between “not permitted” and “nothing there”.
• Usage: GET /v1/usage returns your consumption against the rpm and rpd quotas on the key, so you can alert on your own headroom instead of discovering it as 429s.

data_cadence_s is returned on every surface and line-event response, and its value today is 30: thirty seconds is how often the reference data behind a price can change, at the fastest. Alongside it, data_cadence_tiers_s breaks the figure out by distance to kick-off — {"lt_24h": 30, "24h_96h": 60, "gt_96h": 60}. We refresh events starting within a day twice as often as the rest, so a client that schedules per event rather than per listing spends half the calls on the far ones for the same freshness. Schedule off these fields rather than off a constant of your own, and your poller keeps pace with the data if the numbers ever change.

Those are the classes a first integration meets; the full set of fourteen, with the endpoint of each, is in the reference. Quotas are per client on top of them: an rpm (requests per minute) and an rpd (requests per day) ceiling on the key, both visible from GET /v1/usage together with your actual per-class limits. Exceeding either returns 429 with a Retry-After header and a body naming the class that bit — respect it and you will not be throttled further.

Full error reference →

• Hash chain and Merkle commitments. Every published row is chained; every pass is committed; the daily roots are anchored in Bitcoin via OpenTimestamps. Rows cannot be edited or selectively dropped after the fact.
• Public verifier: github.com/foreline-io/foreline-proofs — python3 verify.py checks the daily roots, the commitment chain and the Bitcoin stamps.
• Tamper-evident from 23 July 2026. As-of history reaches further back — football from 2022 — and rows predating the ledger are served as archive, labelled as such.

Go to the API reference →