Lineval API v1¶
Real-time sports betting data over one API: odds before and during the game, player and game props, futures, live scores and final scoresheets, and an optional verdict on every selection. REST for what you fetch, one WebSocket stream for what changes.
Draft. This documentation describes version 1.0.0 of the contract, which is not released yet. Additions may still land before the release; nothing described here will be removed or renamed afterwards (see Versioning).
Products¶
| Product | Id | What you get |
|---|---|---|
| Pre-game | pregame |
A game's main lines before it starts: moneyline, three-way result, spreads and handicaps, totals and team totals, for the whole game and each period, with alternate lines; ours, and those of the sportsbooks (such as bet365, DraftKings or Pinnacle) with their opening and closing lines |
| Live | live |
Every market of a game in play, live props included, with the score and the clock; and the sportsbooks' lines in play |
| Props | props |
Every other market of a game before it starts: player props and the game's specials |
| Futures | futures |
Outrights and season markets on a whole competition |
| Horse racing | racing |
Horse, harness and greyhound racing: race cards, pari-mutuel pools and official results with their dividends |
| Scores | scores |
The live scoreboard and the final scoresheet of every game, without odds |
| Grading | grading |
Optional add-on: our verdict (win, lose, push, void…) on every selection of our own lines in live, pregame and props |
Each product is sold on its own or combined with others. Your API key lists the products you
bought. All products share one data model, one set of ids and one stream, so combining them
needs no extra work: a game has the same evt_ id in pregame, props, live, scores and
grading, and a verdict names the same mkt_ and sel_ ids you received with the line it
grades, in the same product. Join on those ids (and, for verdicts, on the product: see
Grading).
For example, a key with pregame and scores gets a game's main lines before it starts and its
scoresheet after it ends, under the same evt_. Add grading and the scoresheet comes with our
verdict on each of those lines.
Start here¶
- Quick start: your first request and your first stream, in five minutes.
- Authentication: your key, how to send it, and what it allows.
- Connecting and resuming: REST, the stream, snapshots and deltas,
seq, resuming after a disconnect, and when to reconnect. - Data model: events, markets, selections, prices, status, books, opening lines, rotation numbers and schedules.
- Catalogs: sports, leagues, periods, market types and forms, stat keys, books,
and where we grade (
gradedPeriodsBySport,gradedLeaguesBySport). - Grading rules: how we settle, rule by rule.
- Errors and limits: the error format, every error code and close code, rate and connection limits.
- Changelog: what changed, and our versioning promise.
Examples¶
Each example has exactly the shape the API sends, every field present; the ids are invented.
| Example | What it shows |
|---|---|
| event-pregame.json | A pregame game with its markets: ours, and a DraftKings spread with its opening line |
| event-live.json | A live game with score, clock and markets |
| event-props.json | A props game: a player prop and a game prop |
| event-futures.json | A futures competition |
| events-page.json | A page of events (the scores board) |
| event-family.json | One game across products |
| scoresheet.json | A confirmed scoresheet |
| grading.json | Our verdicts on one game's live lines |
| stream-session.json | A stream session, message by message |
| error.json | An error |
| catalog-market-types.json, catalog-leagues.json, catalog-books.json | A few entries of each catalog |
Conventions¶
- JSON, camelCase. Every field of an object is always present:
nullwhen it is unknown or does not apply. You never need to check whether a key exists. The one list that comes only when asked for is an event'smarkets: an event fetched with its markets, or sent in asnapshot, has it; an event in a page, anevent.upsertor a game's family does not. - Times are ISO 8601 in UTC with milliseconds:
2026-11-14T20:00:00.000Z. - Prices carry decimal and American odds together:
{"decimal": 1.909, "american": -110}. - Ids are opaque and stable strings with a prefix:
evt_,mkt_,sel_,par_,lg_,bk_. Store them; do not parse them. - Names of markets and selections are in English, ready to display.
- Forward compatible. New fields, catalog ids, products and message types may appear at any time within v1. Ignore what you do not know.
Addresses¶
The API lives at https://api.lineval.com.
- REST paths are relative to it:
https://api.lineval.com/v1/live/events. Links the API returns (href,scoresheet,grading) are paths too: prefix them withhttps://api.lineval.com. - The stream is the same host with the
wssscheme:wss://api.lineval.com/v1/stream.
Machine-readable documents¶
The API publishes its own reference, built from the same model that produces every response. None of them needs a key:
| Document | At the API | In this documentation |
|---|---|---|
| OpenAPI 3.1 (REST) | https://api.lineval.com/v1/openapi.json |
openapi.json |
| AsyncAPI 3.0 (stream) | https://api.lineval.com/v1/asyncapi.json |
asyncapi.json |
| Interactive reference | https://api.lineval.com/docs |
API reference |
| Complete clients, in Python and JavaScript (see the Quick start) | https://api.lineval.com/docs/examples/quickstart.py and quickstart.mjs |
quickstart.py and quickstart.mjs |