Connecting and resuming¶
There are two ways in, and most integrations use both:
- REST to fetch: a page of events, one event with its markets, a scoresheet, a grading, the catalogs. Good for a first load, for back-filling and for occasional checks.
- The stream to follow: one WebSocket that sends a snapshot of each product you ask for and then every change, in order, as it happens. It is the only way to keep prices current.
REST¶
| Call | Returns |
|---|---|
GET /v1/{product}/events |
Events without markets, sorted by startAt. Filters: sports, leagues (comma-separated ids), from, to (on startAt), updatedSince (on the event's updatedAt). Paginated |
GET /v1/{product}/events/{eventId} |
One event with all its markets. Narrow with periods, marketTypes, groups (comma-separated) |
GET /v1/events/{eventId} |
One game across the products of your key: where it is offered, and where its scoresheet and verdicts are |
GET /v1/scores |
Scoresheets, sorted by updatedAt. Filters: sports, leagues, updatedSince, confidence=confirmed. Paginated |
GET /v1/scores/{eventId} |
The latest scoresheet of one game. With confidence=confirmed, 404 while the latest is not confirmed |
GET /v1/{product}/grading |
Our verdicts on live, pregame or props, sorted by updatedAt. Filters: sports, leagues, updatedSince. Paginated |
GET /v1/{product}/grading/{eventId} |
Our latest verdicts on one game in live, pregame or props |
GET /v1/catalog/{name} |
sports, periods, market-types, market-groups, stat-keys, leagues or books |
GET /v1/health |
Whether the API is serving: 200 with {"status": "ok"}, or 503 with {"status": "starting"}. No key needed; with your key it also lists, under products, each product of your key with ready, status (ok or degraded, as in feed.status) and events (how many it holds now) |
{product} is the product's id: pregame, live, props, futures or scores (the live
board of scores).
Filters¶
- Every filter is a comma-separated list.
sportsandleaguestake ids from the catalogs; an id with no events gives an empty page.sportandleagueare accepted too, for compatibility (given both, they add up). periods,marketTypesandgroupstake ids from the catalogs too, and are checked: an unknown value is a400 bad_request, never an empty answer, so a typo cannot pass for "no markets".from,toandupdatedSincetake an ISO 8601 date and time with its zone:2026-11-21T18:00:00Z,2026-11-21T18:00:00.000Zor2026-11-21T13:00-05:00(encode+as%2B). A date alone,2026-11-21, is its midnight UTC.fromandtoinclude the time they name: for the whole of 21 November,from=2026-11-21&to=2026-11-21T23:59:59.999Z. Anything else, a time without its zone included, is a400 bad_requestthat names the parameter.updatedSinceon events looks at the event's own fields (its status, score, start time…), not at its markets. To follow prices, use the stream.
Pagination¶
Lists answer {"data": [...], "nextCursor": "..."}. Pass nextCursor back as cursor, with
the same filters, until it is null. The cursor is opaque: do not build or change one.
limit sets the page size: 100 by default, at most 500; a larger value is served as 500.
Caching and compression¶
- ETag. Every
200of the data and catalog routes carries one, weak (W/"…"): events, pages, a game's family, scoresheets, gradings and catalogs. Send it back asIf-None-Matchand, while nothing changed, you get304 Not Modifiedwith no body. A304still counts as a request against your limit. - gzip. Send
Accept-Encoding: gzipand every data and catalog response of 1 KB or more comes compressed; smaller ones are sent as they are. - Catalogs that need no key can be cached for five minutes (
Cache-Control: public, max-age=300).
The stream¶
wss://api.lineval.com/v1/stream?products=live,pregame
products is required: one or more of the products of your key, comma-separated. Optional
filters, each a comma-separated list:
| Parameter | Applies to | Values |
|---|---|---|
sports, leagues, events |
every product | catalog ids, event ids (sport, league accepted too) |
marketTypes, periods, groups |
products with markets | catalog ids; unknown ids close the stream with 4400 |
confidence |
scores |
confirmed: only scoresheets whose confidence is confirmed; a withdrawal still comes as scoresheet.withdrawn |
gradingProducts |
grading |
live, pregame, props: by default, every one your key includes |
since |
every product | where to resume, per product: live:1795286732015467,pregame:1795286711002144 |
A request the stream cannot serve is refused with a close code before any message:
4400:productsmissing, an unknown or unavailable product, an unknown id inmarketTypes,periods,groupsorgradingProducts, aconfidenceother thanconfirmed, or a malformedsince;4401: no key, or a key that is not valid;4403: a product your key does not include;gradingwith a key that has no product of lines (live,pregame,props); or agradingProductsvalue your key does not include.
Messages¶
Every message has the same envelope:
{"type": "market.remove", "seq": 1795286733270154, "ts": "2026-11-21T18:45:33.270Z", "product": "live", "data": {"eventId": "evt_kdmaf647wxusthff", "marketId": "mkt_4ivtdkeuy6gd24da"}}
| Field | What it is |
|---|---|
type |
What the message is, below |
seq |
A point in its product's sequence, the same on every server and across our restarts. See How seq goes. null on a heartbeat |
ts |
When it was sent |
product |
The product it belongs to. null on a heartbeat |
data |
The payload |
| Type | data |
What to do |
|---|---|---|
snapshot.begin |
{} |
A full snapshot of the product follows |
snapshot |
an event with all its markets | Store it, replacing what you had for that event |
snapshot.end |
{"since": seq} |
The snapshot is complete. Deltas follow |
event.upsert |
an event, without markets | Add the event, or replace its fields. Its markets stay as they are |
event.remove |
{"eventId"} |
Drop the event and all its markets |
market.upsert |
a whole market | Add the market, or replace it whole. Never merge fields |
market.remove |
{"eventId", "marketId"} |
Drop the market |
scoresheet |
a game's whole scoresheet | Replace the one you had for that game (scores) |
scoresheet.withdrawn |
{"eventId", "revision", "confidence", "updatedAt"} |
A confirmed scoresheet is no longer confirmed (now provisional or disputed): check anything you settled on it (scores; see Scores) |
grading |
our whole verdicts on one product of lines of one game | Replace what you had for that game and product (grading) |
feed.status |
{"state": "ok" \| "degraded"} |
degraded: the data may be stale. Treat every open market of the product as suspended until ok |
heartbeat |
{} |
Sent every 15 s when nothing else is. Not part of any product's sequence |
A session, message by message, is in stream-session.json: a
reconnect with products=scores,live,grading&since=live:…,grading:…, where scores starts
with a snapshot and live and grading resume where they were.
Every upsert is whole. A market.upsert carries the entire market with every selection; an
event.upsert carries every field of the event (without markets). Replace, never patch.
Each product is a separate board. The same game can be on your pregame, props and
live boards at once, with the same evt_, and a market can have the same mkt_ in live and
before the game. Keep one store per product, keyed by id: an event.remove in live does not
remove the game from scores.
feed.status is sent once per product right after its snapshot (or after the missed
messages of a resume), and again whenever it changes. It is an overlay on the whole product:
while degraded, show prices greyed out and accept no bets on them. When it returns to ok, the
product is back in sync and each market's own status applies.
Snapshots and deltas¶
On connect, each product you list sends snapshot.begin, one snapshot per event (filtered by
your filters), snapshot.end and its feed.status; then only changes. In scores, each event
of the snapshot is followed by its scoresheet when the game has one. The snapshot of grading
holds no games: catch up with GET /v1/{product}/grading?updatedSince=… after it (see
Grading).
How seq goes¶
- After a snapshot, each
event.*,market.*,scoresheet,scoresheet.withdrawnandgradingmessage has a higherseqthan the one before. snapshot.begin,snapshot.endandfeed.statusare not changes: they carry theseqof the point they mark, which the message before may share.- Inside a snapshot, each event and its scoresheet carry their own
seq, never higher than the snapshot'ssince, in no order: they are not a place to resume from. Resume fromsnapshot.endon. - A reconnect that cannot resume gets a fresh snapshot, whose
seqmay be lower than yoursince.
So never drop a message because its seq is not higher than the last one: seq says where to
resume, not what is new.
Resuming with since¶
Keep, per product, the since of its snapshot.end and then the seq of every message you
apply after it:
if kind == "snapshot.begin":
in_snapshot.add(product)
since.pop(product, None)
elif kind == "snapshot.end":
in_snapshot.discard(product)
since[product] = msg["data"]["since"]
elif msg["seq"] is not None and product not in in_snapshot:
since[product] = msg["seq"]
When you reconnect, pass every product's position:
/v1/stream?products=live,pregame&since=live:1795286732015467,pregame:1795286711002144
- If the server still holds what you missed, you get exactly those messages, in order, and no snapshot.
- If not, you get a fresh snapshot of that product. Replace its board with it: the events and
markets you hold for that product. Keep the scoresheets and gradings you hold, and catch up on
them with
updatedSince(a snapshot ofscorescarries only the games still on the board, and one ofgradingcarries none). - A product you list without a
since(or whose connection dropped before itssnapshot.end) starts with a snapshot.
A server holds the last 20 000 messages of each product (5 000 for grading): for live at
its busiest, a few minutes. Positions work on any of our servers: a reconnect may land on another
one and resume there; if that server does not hold your position (it has just started, or
re-synced), you get a fresh snapshot instead.
Nothing is skipped in silence. On one connection, every message your filters let through
comes, in order; if that cannot be kept (you fall behind, or the server re-syncs), the server
closes the stream (4429, 1013). A resume with since gets exactly the messages after it, or
a fresh snapshot: never part of them. seq values are not consecutive (they come from a clock),
so a jump between two seq is normal and says nothing is missing.
Keeping the connection healthy¶
- A
heartbeatcomes every 15 s when nothing else does. No message for 45 s means the connection is dead: close it and reconnect withsince. - Connections drop now and then on the way (a network, a proxy): your library reports
1006. That is normal: reconnect withsince, with back-off. - Any frame you send is accepted and ignored; you do not need to send anything.
- Keep up. Process messages as they arrive and do heavy work off the socket's thread. A
client that falls too far behind is closed with
4429(reasonnot keeping up with the stream). Reconnect withsince: you lose nothing.
When the stream closes¶
Reconnect with since after every close except the three marked "no". Servers restart for
deploys and there is more than one: do not reconnect only on one code.
| Code | Meaning | What to do | Reconnect on its own |
|---|---|---|---|
1000 |
Closed normally, by you or by a proxy on the way | If you still want the stream, reconnect with since |
yes |
1001 |
A server or a proxy on the way is shutting down | Reconnect with since, after a short random wait (up to 1 s) |
yes |
1006 |
Never sent: your library reports it when the connection dropped with no close frame (network, proxy) | Reconnect with since, with back-off |
yes |
1011 |
An error of ours while serving the stream | Reconnect with since, with back-off; tell us if it repeats |
yes |
1012 |
The server is restarting (a deploy); another server takes your reconnect | Reconnect with since at once, after a random wait of up to 1 s |
yes |
1013 |
Starting up, or re-synced: what you hold may not match | Reconnect with since, after a short back-off |
yes |
4400 |
A query parameter is not valid; the reason names it | Do not retry the same URL: fix the request | no |
4401 |
No key, an unknown key, or a key revoked while connected | Do not retry: check your key with us | no |
4403 |
Your key does not include a product you asked for (or lost it) | Reconnect without that product, or ask us to add it | no |
4429 |
Either you were not keeping up (reason: not keeping up with the stream) or you are over your connection limit (reason: over your connection limit) |
Not keeping up: reconnect with since and process faster. Connection limit: close another connection, or wait 30 s before retrying |
yes |
Any other code: reconnect with since, with back-off.
Back-off: wait 1 s, then double up to 30 s, each wait with up to 1 s added at random, so that
many clients do not reconnect in the same instant. Go back to 1 s once a connection has lasted a
minute. A connection refused before it opens (HTTP 503) counts as a 1013.
Catalog updates¶
The catalogs (sports, periods, market types, stat keys, leagues, books) are fetched over REST, not sent on the stream. Cache them and refresh them once a day:
- ids are never renamed or reused;
- new ids may appear at any time. When a message carries an id you do not know yet, refetch the catalog; if it is still not there, ignore what carries it;
gradedPeriodsBySportandgradedLeaguesBySportfollow our grader and our daily measurement: they gain and lose entries (see Catalogs).
Every market and selection also carries its display name, so you can show a market whose type
you have not cached yet.