Documentation
Three calls to a live board.
The full reference is generated from the API's own contract and served by the API, so it cannot drift from the code. This page is the quick start, the limits, and how the account works.
Before the first call
Get a key.
1
Sign up
An email address and a password. Free during the beta, no card.
2
Create a key
Dashboard → API keys → Create. The key is shown exactly once: copy it then. A label tells keys apart.
3
Keep it secret
In an environment variable (ODDSHOUSE_KEY) on a server, never in a browser bundle or a shared URL. Revoke a leaked key in one click.
4
Call the API
https://api.oddshouse.io/v1, with the key in x-api-key or Authorization: Bearer. The WebSocket also takes ?key=.
The dashboard
At oddshouse.io/app after signing in.
- Overview
- Your plan as the feed enforces it, your keys, today's requests and the last 24 hours of frames and data.
- API keys
- Create (shown once), label and revoke keys; up to 5 live at a time. Only a key's prefix is shown afterwards.
- Usage
- Requests today by endpoint and by key, and the last 24 hours by the hour. The live bucket and open sockets: GET /v1/account/usage with the key.
- Send feedback
- A link to support@oddshouse.io: what broke, what is missing. The event id, the book and the time in UTC make a report useful.
Quick start
Authenticate, read, follow.
STEP 1
Authenticate
Every call starts with https://api.oddshouse.io/v1. Send the key in a header; the ?key= form exists for WebSocket clients that cannot set headers. Keep keys out of shared URLs.
API=https://api.oddshouse.io/v1
# any of the three; the header forms keep the key out of logs
curl -H "Authorization: Bearer $ODDSHOUSE_KEY" $API/me
curl -H "x-api-key: $ODDSHOUSE_KEY" $API/me
curl "$API/me?key=$ODDSHOUSE_KEY"/v1/me answers with your plan, which is exactly what the feed will let you see:
{
"customer": "cus_3f9a1c27b84e5d60",
"usage": "/v1/account/usage",
"plan": {
"id": "beta",
"leagues": "*",
"books": "*",
"props": true,
"rateLimitPerMin": 1200,
"maxAltLines": null
}
}STEP 2
Read the board
List events for a league, then fetch one event's odds map. Every snapshot carries asOf and the stream cursor it reflects.
# The NFL board: one summary row per event,
# stamped with the stream cursor it reflects
curl "https://api.oddshouse.io/v1/events?league=nfl&limit=50" \
-H "x-api-key: $ODDSHOUSE_KEY"
# One event: the flat odds map keyed by oddID,
# every book inside each odd
curl "https://api.oddshouse.io/v1/events/evt_2f9c1e" \
-H "x-api-key: $ODDSHOUSE_KEY"
# The player-prop screener: one row per (player, stat),
# widest gap between books first
curl "https://api.oddshouse.io/v1/props?league=nfl&shared=1&sort=gap" \
-H "x-api-key: $ODDSHOUSE_KEY"STEP 3
Follow the stream
Open the socket, optionally subscribe to a narrower scope, and apply every frame whose cursor is after your snapshot's. Remember the last cursor: sockets are recycled every 10 minutes, and a reconnect with it resumes exactly where you were.
import WebSocket from "ws";
const URL = "wss://api.oddshouse.io/v1/updates";
let epoch = null, cursor = null;
function connect() {
const key = process.env.ODDSHOUSE_KEY;
const ws = new WebSocket(`${URL}?key=${key}`);
ws.on("open", () => ws.send(JSON.stringify({
action: "subscribe",
filters: {
leagues: ["nfl"],
books: ["draftkings", "fanduel"],
market_groups: ["player_props"],
},
// after a reconnect: replay exactly what was missed
...(cursor && { resume_from: cursor, epoch }),
})));
ws.on("message", (raw) => {
const frame = JSON.parse(raw);
if (frame.action === "hello") epoch = frame.data.epoch;
if (frame.cursor) cursor = frame.cursor;
if (frame.action === "line_update") {
const { book, player, market, prev, price } = frame.data;
console.log(book, player ?? market.type, prev, "->", price);
}
if (frame.action === "resync_required") snapshotAgain();
});
// sockets are recycled every 10 minutes: reconnect and resume
ws.on("close", () => setTimeout(connect, 500));
}
connect();Reading a price
Three rules that prevent most integration bugs.
1
price is decimal
american is the same price as a string. price: null means no usable price. It is never 0.
2
status is separate
OPEN, SUSPENDED or CLOSED. A price on a suspended selection is display-only.
3
the line is per book
byBookmaker.<book>.overUnder (or .spread) is that book's main line; its other lines come in altLines with includeAltLines=true. Two books on one odd can sit on different lines.
Identity
The odd id.
The same id on every book. The line is deliberately not part of it: it lives in each book's cell as overUnder or spread, because two books can sit on different lines for the same odd, and the ladder beneath a main line belongs to that book alone.
Endpoints
Everything under /v1.
| Method | Path | Returns |
|---|---|---|
| GET | /v1/me | Your key's customer and the plan it is checked against. |
| GET | /v1/account/usage | Today's requests by key and endpoint, the rate-limit bucket, the sockets open on the serving process. |
| GET | /v1/events | The board: one summary row per event, cursor-paginated, filterable by league, book, phase, date. |
| GET | /v1/events/:id | One event's flat odds map and its players: every odd, each book's main line; the ladders with includeAltLines=true. |
| GET | /v1/odds | Odds across many events, 50 to a page: the main game lines by default, every market with main=false; by league, day, oddID or book. |
| GET | /v1/props | The player-prop screener: one row per event, player and stat with each book's main line; stat takes the canonical id (RECEIVING_YARDS); sort by start, gap, moved or books. |
| GET | /v1/schedules | Upcoming events without prices, with the books already pricing them. |
| GET | /v1/changes | The change log over HTTP, from a cursor, for clients that poll instead of holding a socket. |
| GET | /v1/leagues · /v1/books · /v1/stats · /v1/markets | Reference: leagues and their live coverage, the books and what each prices, stat ids, every oddID pattern. Also /v1/sports, /v1/periods, /v1/bet-types, /v1/tournaments. |
| GET | /v1/mappings/players · /teams · /events | Our ids to external ones (balldontlie, ESPN, Sportradar …) and back with external=source:id. Player ids embed the balldontlie id: nfl_p_738. |
| WS | /v1/updates | The stream: hello, subscribe, one frame per change, resume by cursor and epoch. |
| GET | /v1/docs | The reference itself: OpenAPI, llms.txt, guides and real example responses. Public, no key. |
The stream
Every frame the socket sends.
- hello
- First frame. Your plan, the schema version, the stream epoch and cursor, the connection id, the outcome of any resume.
- subscribed
- Reply to subscribe. The effective scope after intersecting with the plan, and what was dropped.
- subscribe_rejected
- A subscribe sent while a resume or another subscribe was still running. Wait for resumed or subscribed, send it again.
- line_update
- One price or status change: oddID, book, line, prev, price, dir, main, deep link, ts_received, ts_broadcast.
- score_update
- A live score changed: home and away score, period, clock, which book reported it.
- updates
- With batch=1: a burst of frames as one message, every cursor kept, nothing coalesced.
- cursor
- After 10 seconds of silence: the stream is alive and this is the newest cursor. No odds; adopt the cursor.
- resumed
- The replay after resume_from is complete; what follows is live.
- resync_required
- The cursor could not be honoured or continuity was lost. Snapshot again, then apply frames after its cursor.
Limits
What a client runs into.
The numbers are the beta's, the same for every account; your dashboard shows the plan your key is checked against.
- Requests
- 1,200 a minute per key during the beta: a token bucket refilled continuously, so a burst can spend it at once. Every response carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset (seconds); over it, 429 with Retry-After.
- Sockets
- 3 concurrent connections during the beta. One more is refused with 429 before the upgrade; close one you no longer read.
- Socket lifetime
- A socket is closed after at most 10 minutes, without a close frame (1006 on most clients). Reconnect at once with resume_from and epoch: nothing is lost.
- Resume window
- About 15 minutes. An older cursor gets resync_required: take fresh snapshots and apply frames after their cursor.
- Restarts
- While the feed restarts (about 100 s per deploy) REST and the socket upgrade answer 503 with Retry-After: 5. Honour it; a resume across a restart replays exactly what moved.
- Keys
- Up to 5 live keys per account, issued and revoked in the dashboard. A key is shown once; we keep only its hash.
Errors
Every status, and what to do.
A plain JSON body with an error string. A plan never answers 403: what it does not include is left out.
- 400
- Invalid query, cursor or input. Fix it from the endpoint's parameter table; do not retry unchanged.
- 401
- Missing, unknown, revoked or suspended key. Check where the key is sent and the account's state.
- 404
- Unknown route or event, or an event outside your plan. The body's hint names the index.
- 405
- Anything but GET or HEAD: every /v1 route is read-only.
- 410
- The change history cannot reach your cursor any more. Take a fresh snapshot and resume from its cursor.
- 429
- Request rate or socket allowance used up. Honour Retry-After; close a socket you no longer read.
- 500
- Unexpected. Retry with backoff; report the route and the time if it persists.
- 503
- The feed is restoring after a restart. Honour Retry-After (5 s) and retry.
Reference
Served by the API itself.
- OpenAPI documentgenerated from the contract types; the source of truth
- API index for agentsevery endpoint page, data type and example, with sizes
- WebSocket guideframes, subscriptions, the reconnect model, limits
- Odd idsthe five-part grammar and every vocabulary
- Leagues and booksevery book's id and the leagues it is collected for
- Errorsevery non-200 body and what to do about it
For AI agents
Point your coding agent here.
Two plain-text files on this site follow the llms.txt convention: a short index, and the whole integration guide in one file (the key, the base URL, the limits, the price rules, the endpoints, the stream and its reconnect model, the coverage, working samples). Paste either into an agent, or give it the URL.
Status
When something breaks.
There is no public status page yet; incidents are reported by email to every account. Something looks wrong on your side? Write to support@oddshouse.io with the endpoint or the frame, the event id, the book and the time in UTC; for a socket, the connection id from its hello frame.
Join the beta. Tell us what to fix.
Every league, every sportsbook, player props and the stream, free for every account while we polish the feed. The key you get today is the key you keep.