SportWizzard API

Getting started

The SportWizzard REST API is served from a single base URL. Every endpoint lives under /api/v1 and returns JSON.

Authentication

Authenticate by sending your API key in the X-Api-Key request header. Keys are issued through your account — sign up, open your account, and create a key under the API Keys tab. Reference endpoints (leagues, sportsbooks, teams, players, markets) are free and require no key.

curl "https://api.sportwizzard.com/api/v1/events?league=mlb" \
  -H "X-Api-Key: sw_live_your_api_key_here"

Response envelope

Every response uses the same envelope. Results are in data; list endpoints add an opaque nextCursor and a meta object with count and an updated timestamp.

{
  "success": true,
  "data": [ /* … */ ],
  "nextCursor": "opaque-cursor-string-or-null",
  "meta": { "count": 50, "updated": "2026-07-09T16:41:27Z" }
}

Pagination

List endpoints are cursor-paginated. Pass limit to size a page, then take the nextCursor from the response and send it back as ?cursor=… for the next page. Cursors are opaque — treat them as blackbox tokens. When nextCursor is null, you have reached the end.

Freshness & caching

Live-odds responses carry an ETag. Send it back on the next call via If-None-Match to get a cheap 304 Not Modified when nothing has changed. To sync efficiently, poll /api/v1/odds/updated?since={timestamp} for just the rows that changed.

The odds data model

Understand this and the rest of the API falls into place.

Events are the spine

Everything hangs off an event — a single game or match, with homeTeamId/awayTeamId, startTime, league, and status. Odds, box-score stats, and per-game context are all keyed by eventId. The normal path: list events, take an id, then pull that event's board via /v1/events/{id}/odds.

Odds are a flat array

The odds feed is not nested. It's a flat list with one row per (sportsbook × market × selection), and every row is fully self-describing — it repeats its eventId, sportsbook, market, selection, side, line, and price, so you never walk a tree to know what a row means. One shape describes a baseball run line, an NBA player-points prop, a soccer 3-way moneyline, and a golf outright — which makes odds trivial to filter, join, and load into a table or dataframe.

The composite id

Each row's id is a stable composite key of the form {eventId}:{sportsbook}:{marketSubtype}:{selectionId} (the selectionId is a time-ordered UUIDv7). It stays the same across polls for the same line, so use it as your primary key to upsert/dedupe: a price or line move keeps the same id and only changes priceAmerican/priceDecimal/line/updated.

A real, trimmed odds row:

{
  "id": "31cd6744-…-c4a7d1fce547:ballybet:SPREAD:019f495d-8558-7324-…",
  "sportsbook": "ballybet",
  "league": "mlb",
  "eventId": "31cd6744-9444-4fbd-b25c-c4a7d1fce547",
  "market": "SPREAD",
  "marketSubtype": "SPREAD",
  "period": "FULL",
  "selection": "KC Royals",
  "side": "AWAY",
  "teamSide": "AWAY",
  "teamName": "KC Royals",
  "line": -1.5,
  "priceAmerican": 200,
  "priceDecimal": 3.00,
  "suspended": false,
  "eventStartTime": "2026-07-10T23:05",
  "updated": "2026-07-10T14:53:35Z"
}

Field glossary

Raw odds rows carry book prices only — there is no fairOdds/devigged field on an odds row. No-vig fair value and cross-book comparison live on the derived /v1/edges and /v1/arbitrage signals, computed from these same rows.

Reading /v1/edges honestly: the edge value is the gap between a DFS line and the most favorable sportsbook's vig-removed implied probability — so it's optimistic by construction, and an edge resting on a single book's quote can just be a stale line. Treat it as a screen for soft DFS lines to verify yourself, not a proven +EV bet. /v1/arbitrage margins hold only if every leg fills at the quoted price before it moves.

Four ways to read odds

Live board — /v1/odds (and /v1/events/{id}/odds, /v1/players/{id}/odds, /v1/teams/{id}/odds): cache-served, seconds-fresh — a point-in-time read of what's bettable now. Delta feed — /v1/odds/updated?since={ts}: only rows changed since your last sync, for cheap continuous polling — scopeable with the same league / sportsbook / market filters as /odds. Snapshot — /v1/snapshot: the entire live board across every book and league as one gzip pull, to bootstrap a full local copy. Historical — /v1/historical/odds: point-in-time replay of a past event for backtesting (paid plans, ×5 credits).

Rule of thumb: snapshot to bootstrap → /odds/updated to stay in sync → /odds (scoped) for targeted reads → /historical/odds to replay the past.

Scoping odds

Unscoped, /v1/odds spans every league and book and paginates hard — always scope it: by event (/v1/events/{id}/odds), by entity (/v1/players/{id}/odds, /v1/teams/{id}/odds), or by filter on /v1/odds with league, sportsbook, market, event_id, player_id, and team_id (combine freely), plus cursor and limit. league, sportsbook, and market each take up to 20 comma-separated values, matched any-of (e.g. sportsbook=draftkings,fanduel). Two shaping params apply on every live-odds read: odds_format (american | decimal | probability | all, default both price fields; probability returns implied probability instead) and is_main=true (keep only each market's primary line per book, collapsing alt over/under ladders to the main number; not on the delta feed).

Rate limits & tiers

1 credit = 1 event served — empty responses and 304s are free, and reference endpoints never consume credits. Annual billing = 2 months free. See full plan details on the pricing page. Usage is returned in response headers so you can track consumption programmatically.