Three products, one key, one identifier

# the mapping job: everything kicking off in the next 48 hours, as CSV
curl -s "https://api.foreline.io/v1/catalog/events?hours=48&format=csv" \
  -H "X-Foreline-Key: $FORELINE_KEY"

event_id,sport,league,home,away,starts,markets,updated_ts,league_id,sport_id
1632737351,football,UEFA - Champions League Qualifiers,Shamrock Rovers,Ararat-Armenia,2026-07-28T19:00:00Z,moneyline|spread|totals,1785262578.971,2632,29

# the same slice as JSON
curl -s "https://api.foreline.io/v1/catalog/events?hours=48" \
  -H "X-Foreline-Key: $FORELINE_KEY"

league,sport,events,next_start,league_id
Argentina - Liga Pro,football,4,2026-07-28T22:00:00Z,215171
USA - Major League Soccer,football,15,2026-07-29T00:00:00Z,214211

What happens when an id is not ours

Nothing is inferred and nothing is silently dropped. Every endpoint that takes an event rejects the row explicitly and tells you which one it was, so a bad mapping surfaces on the first call rather than in a reconciliation weeks later.

• There is no resolve endpoint. We do not offer a “send us team names and we will find the event” helper in this release. A helper that is wrong some of the time moves our error into your settlement, and we are not prepared to publish one without measured accuracy figures alongside it.
• Pull the catalog before kick-off, not after. Team names and league come from the fixture card, and a card can drop out of the live window once the match is under way. The row keeps its event_id and stays fully serviceable; the names may come back empty. The n_unnamed counter in the response tells you how many rows in that page are affected, so schedule your mapping job on ?hours= and it never sees them.
• Our event_id is an integer and it does not change when a line moves, a market is added, or the event is rescheduled.
• Match on event_id, filter on league_id and sport_id. Those three are the only identifiers in the product. Everything else about an event — league, home, away — is display text, and text can be rewritten upstream without warning. If your integration compares any of those strings to decide which event or competition something is, that comparison is the part that will break. The same two ids come back on GET /v1/surface and in batch exports, so a league dictionary you build once from the catalog joins onto everything else by id.
• There are no team ids, and this is upstream, not a choice. Our reference data carries teams as names only — there is no team identifier for us to pass on, and inventing one would mean publishing a mapping we cannot guarantee. So the team-level work is a one-off: at onboarding you reconcile your team list against ours using the catalog, with a human confirming the ambiguous cases. After that you never match teams again — you hold our event_id, and a team renamed upstream cannot reach your integration. If you would rather not do even that once, ask us: we will do the reconciliation with you against your list before you go live.

# 1. take an id from the catalog — the first event that has not kicked off yet.
#    (the catalog window also reaches six hours back, so do not just take .events[0])
EVENT_ID=$(curl -s "https://api.foreline.io/v1/catalog/events?hours=48" \
  -H "X-Foreline-Key: $FORELINE_KEY" \
  | jq -r '[.events[] | select(.starts > (now|todate))][0].event_id')

# 2. score one bet on it, stamped now — which is before that kick-off
curl -s -X POST "https://api.foreline.io/v1/score" \
  -H "X-Foreline-Key: $FORELINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "a_7731",
       "bets": [{"event_id": '$EVENT_ID', "market": "ah", "line": -0.25,
                 "side": "home", "odds": 1.95, "stake": 120,
                 "placed_at": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}]}'

→ 200 { "account_id": "a_7731", "accepted": 1, "rejected": [],
        "n_bets": 1, "n_scored": 0, "n_pending": 1, "score": null, … }

Checkpoints: when a flag can appear

The account is not re-judged on every bet. Two components are evaluated at fixed checkpoints, counted in scored bets, and a flag is raised the first time either one crosses its threshold:

• Below 5 scored bets the score is informational. It is returned, and it is real, but no flag can be raised. Do not wire an automatic limitation to it.
• The flag is sticky. flag_k records the checkpoint at which it fired, so an account that clears the bar at 10 does not lose the flag at 20 — you keep the audit trail of why the decision was made.
• Thresholds are set per contract during onboarding, so the score can be tuned to your appetite without changing a line of your integration. The false-positive budget behind them is stated in the reference.

Batch or live — pick per use case

Both shapes reach the same state for the same bets. Sending the same bet twice does not count it twice: the second copy is refused as duplicate (matched by bet_id, or by content when you send none) and reported in n_duplicate. Replaying a batch after a timeout is therefore safe — though deduplicating on your side still saves the round trip.

• Address legs by our event_id, exactly as everywhere else. A combination is only as well-matched as its worst leg.
• Bands travel through. A combination built on src: "table" rungs is visibly less certain than one built on quoted ones — read the joint number against its band rather than as a point estimate.
• The known limitation is published, not buried: on the “home and over” family the model underprices the joint probability by 4.4–5.3 pp in the middle buckets, and the band is widened where the miss lives. See the product page before you take the number at face value on that family.
• Delivery is scoped by contract. Joint pricing arrives as an audit first and as a feed afterwards; the field specification for the retro batch is provided under NDA rather than published here.
• Give the historical calls a long client timeout — 30 s or more. A coupon priced with ?asof=, and every ticket in POST /v1/parlay/audit, is rebuilt from the feed archive rather than read from a cache: measured end to end at p50 2.1 s, p95 9.9 s, worst 18.0 s. The server has its own 25 s budget and always answers inside it, marking anything it could not reach rather than dropping it — a 10 s client timeout throws that answer away and makes the retry do the work twice. Keep the short timeout for the per-quote check, which is milliseconds. Details.

Keeping a local mirror is one call in a loop: GET /v1/surface?since= returns every surface that changed after your cursor, in full, and hands back next_cursor. Pass it back unchanged on the following call, and while more is true, go straight to the next page instead of waiting for your poll interval.

The same loop, unchanged, reads the other two feeds — GET /v1/line-events for main-line changes and GET /v1/alerts for the alert journal. Same since parameter, same next_cursor, same more. Nothing else about a feed needs to be special-cased, and there is no second way to page: the field to loop on is next_cursor, and only that field. The full rules live in the reference, under Cursors & paging.

• Never build a cursor yourself, and never parse one. It is a compound value whose shape differs per endpoint — the line-event feed already needs three components, because one event can move its handicap and its total inside the same tick. Store it as a string and pass back exactly what we returned.
• A cursor you stored months ago can now be refused. The history depth of your plan applies to /v1/line-events as well as to ?asof=: resuming from a since further back than your contract allows answers 403 with your_plan_days, requested_days_back and earliest_allowed_since. Clamp your stored cursor to earliest_allowed_since and replay forward from there. Starting the feed from scratch with since=0 is never refused.
• ?asof= on the surface takes epoch seconds, not ISO. Instants inside our live payloads — ts, server_ts, next_since, updated_ts, the asof echo — are epoch seconds as JSON numbers; only calendar fields such as starts are ISO strings. An ISO value on /v1/surface?asof= comes back as 400 {"error": "bad numeric parameter: asof"}, while the parlay endpoint accepts either. Convert once at the edge of your client and keep the numeric form inside it: which field is which shape. Two more rejections on that parameter: it must travel with an event_id — on its own it is now 400 rather than a silent live answer — and an instant in the future is 400 {"error": "asof is in the future"} once it is more than five seconds past our clock. That five-second allowance is deliberate, so that a client whose clock runs slightly fast still gets an answer; it is a tolerance for skew, not a window to build on, and inside it you are served the latest surface we hold rather than a future one.
• Inside a downloaded export file, every timestamp is ISO — including the ones that are epoch numbers live. This is the one exception to the rule above, and it bites loaders written against the live endpoints. In both surface_asof and line_events files, and in CSV and JSONL alike, asof, updated_ts, ts and starts are all ISO-8601 UTC with Z — "2026-08-17T00:00:00Z", never 1787011200. Parse every timestamp column in a file as ISO and the same loader reads both kinds.
• A parameter present but empty is a 400. ?league= is not the same as omitting league: it answers 400 {"error": "league was given with an empty value"} with a hint, and it applies to every parameter we recognise — event_id, since, limit, asof, sport, league_id and the rest. It is the most common integration error we see, and it is nearly always an unset variable interpolated into a URL or an optional filter that serialises as "" instead of being dropped. Strip empty values where you build the query string. A parameter we do not recognise is ignored instead, so a misspelt filter name returns 200 with an unfiltered answer — assert that a filter narrowed the result before you trust it.
• Schedule off data_cadence_s, which is returned on surface and line-event responses, rather than off a fixed timer: it tells you when a new value can exist at all, so polling faster only re-reads the same updated_ts.
• Refresh the catalog on its own schedule. Once a day covers a normal book; run it on ?hours= so new fixtures enter your mapping before anyone can bet on them — and remember that window also reaches six hours backwards, so it returns matches already under way.
• Handle 429 by reading Retry-After, not by backing off blindly. The catalog and the bulk delta share the bulk class, so a catalog refresh in the middle of a sync loop competes with it — put the catalog job on a different minute.

Full API reference →