API Reference

Base URL, response envelope, error codes, rate limits, and common parameters.

Base URL

https://api.oddsstream.io

All endpoints are under this base URL. No version prefix — the API is currently at v1.

Authentication

Every request requires an API key in the X-Api-Key header:

curl "https://api.oddsstream.io/api/odds" \
  -H "X-Api-Key: os_live_YOUR_KEY"

Keys are issued from your dashboard at oddsstream.io/dashboard/keys. Key format: os_live_<32-char-hex>.

---

Response Envelope

All successful responses follow this shape:

{
  "data": [...],
  "meta": {
    "count": 142,
    "rate_limit_remaining": 4987
  }
}

For single-object responses (e.g. GET /api/events/{id}), data is an object, not an array.

---

Error Format

{
  "error": {
    "code": "live_not_on_plan",
    "message": "Live odds require the Pro Live plan.",
    "upgrade_url": "https://oddsstream.io/pricing"
  }
}

HTTP Status	Error Code	When
400	bad_request	Invalid query parameter value
401	unauthorized	Missing or invalid X-Api-Key
403	live_not_on_plan	Requested is_live=true without Pro+ Live plan
403	websocket_not_on_plan	Requested WS token without a plan that includes WebSocket
403	bookmaker_not_configured	Free plan: no bookmaker selected in dashboard
403	bookmaker_forbidden	Free plan: requesting a different bookmaker than selected
404	not_found	Event slug not found in active data
409	key_limit_reached	Already at the 5-key cap — revoke one first
429	rate_limit_exceeded	Too many requests — see X-RateLimit-Remaining
500	internal_error	Server error — safe to retry with backoff
503	service_unavailable	Database temporarily unavailable

---

Rate Limits

Limits are per API key:

Plan	Rate limit	WebSocket	Live endpoints
Free	200 req/day	30 connections/day	No
Pro	5,500 req/hr	Not included	No
Pro+ RT	5,500 req/hr	Unlimited	No
Pro+ Live	5,500 req/hr	Unlimited	Yes

Rate limit headers on every response:

X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1745160060

---

Common Query Parameters

These filters are accepted on all list endpoints unless stated otherwise:

Parameter	Type	Description
sport	string	Filter by sport name — case-insensitive (e.g. Football, Tennis, Basketball)
competition	string	Filter by competition code — exact, uppercase (e.g. EPL, NBA, LIG1)
bookmaker	string	Filter by bookmaker name — exact, case-sensitive (e.g. Winamax, Betclic)
limit	integer	Max results returned. Each endpoint has its own cap.

---

Competition Codes

Competition codes are short uppercase identifiers used across all endpoints. They are stable — they don’t change with bookmaker translations.

Examples:

Code	Competition	Sport
EPL	English Premier League	Football
LIG1	Ligue 1	Football
BUND	Bundesliga	Football
SERA	Serie A	Football
LIGA	La Liga	Football
UCL	UEFA Champions League	Football
NBA	NBA	Basketball
NFL	NFL	AmericanFootball
NHL	NHL	Hockey
MLB	MLB	Baseball
ATP	ATP Tour	Tennis
WTA	WTA Tour	Tennis
EFL	English Football League	Football
ERED	Eredivisie	Football
MLS	MLS	Football

Use GET /api/sports to discover all active competition codes at runtime.

---

Market Types

market_type	Description	Sports
moneyline	Win/Draw/Win (1X2) or Head-to-Head	All
spread	Asian Handicap / Points Spread	Football, Basketball, Hockey
total	Over/Under totals	All
btts	Both Teams to Score (Yes/No)	Football
double_chance	Double Chance (1X, X2, 12)	Football
draw_no_bet	Draw No Bet (Home/Away)	Football
3way_handicap	European Handicap (3-way)	Football
total_games	Total Games Over/Under	Tennis
games_handicap	Games Handicap	Tennis
team_total	Per-team total (Home/Away Over/Under)	Football, Basketball
player_prop	Player performance props	Basketball, Hockey, Baseball
yes_no	Binary Yes/No markets	Various

---

Period Values

The period field on every odds row indicates which portion of the match the market covers:

period	Football	Basketball	Hockey	Tennis
0	Full time	Full game	Full game	Match
1	1st Half	1st Quarter	1st Period	1st Set
2	2nd Half	2nd Quarter	2nd Period	2nd Set
3	—	3rd Quarter	3rd Period	3rd Set

Full-time (period: 0) markets dominate. Half-time and quarter markets are available for most sports.