Moving from v2 to v1.

What changes

• The base URL becomes https://api.sockodds.com/v1. Every v2 route is retired at the switch and then answers 410 Gone.
• Keys are sent only as a bearer token.
• Events, players, markets and outcomes have new identifiers. Previous identifiers are not translated.
• Responses share one envelope, field names are lower case with underscores, and prices are decimal.
• Live prices stream over a WebSocket on the Pro plan.

Keys and your account

Your account, keys and plan carry over. Send the same key to v1 in the Authorization: Bearer header. Keys sent in any other header or in the URL query are not accepted by v1. Keep keys on your server, out of browser code and out of URLs.

Usage is counted in objects: each returned record counts as one, plus one for every bookmaker price inside it. Check usage, rotate a key or manage billing on your account page.

Identifiers

v1 issues its own identifiers. There is no lookup from a previous identifier to a new one, so saved references must be rebuilt from v1 responses. Find events through /v1/events by league and start time, then store the returned identifiers.

If you already hold official event ids, /v1/events/lookup finds our event directly: an ESPN event id, an AFL match id for AFLW or an NRL match id for the Rugby League World Cup. Send one id, or up to 100 at once. Bookmaker listing ids cannot be looked up.

Sports, leagues, bookmakers, markets, periods, sides and teams use readable lower case keys such as nfl, sportsbet or full. Discover them from the catalogue routes rather than hard coding them.

Routes

All v1 routes sit under https://api.sockodds.com/v1. Each links to its generated reference.

Fields and responses

• Every response is data, meta and links. Lists page with a cursor: follow next in links unchanged until it is null.
• Times are UTC in ISO 8601, for example scheduled_start, observed_at, starts_after and starts_before.
• Odds are grouped by market: each market and outcome appears once, and each outcome carries line, side and prices, one per bookmaker, best first. Each price carries bookmaker, decimal_odds, implied_probability and observed_at. Implied probability is one divided by the decimal price. A price that is stale or withdrawn is null, never zero. Add group_by=bookmaker for one block per bookmaker instead.
• Markets carry their period and subject, so a selection can be read without guessing.
• Events list participants, each with a role. Team sports use home and away. Tennis and UFC use competitor_1 and competitor_2, in the order the event's fixture source lists them, and outcome sides use the same names.
• Results give each outcome a verdict: won, lost, void or dead_heat. A void returns the stake. A dead heat pays dead_heat_factor of the stake at the quoted price and loses the rest, so a drawn AFLW head to head with a factor of 0.5 pays half.
• A result can arrive in parts. Each market settles as soon as the official figures for it are in, so a match's settlement is partial while some markets wait, and pending_markets says how many. Outcomes already settled never change unless the result is marked corrected.
• Errors use application/problem+json with a status, a title and a detail you can show or log.

Streaming

The v2 stream is retired with the other v2 routes. On the Pro plan, open a WebSocket to /v1/stream/odds with your bearer key for one event, or for up to 20 events in one league.

• A fresh snapshot or a heartbeat arrives every 15 seconds. Each refresh counts towards your allowance like an ordinary odds request.
• Up to 2 open streams per key. A stream lasts at most 1 hour, then reconnect.
• The stream is read only. Close codes tell you whether to reconnect, narrow your filters or read faster; they are listed in the reference.

Recorded history

v1 history holds only prices we recorded ourselves, under the new identifiers: from 8 October 2026 for every league, and back to 22 December 2025 for leagues whose earlier recordings were converted. The history guide lists each league's first day. History is on the Pro plan, one event at a time, in windows of up to 24 hours.

Plan the move

1. Download the OpenAPI contract and read the reference.
2. Send your existing key as a bearer token to the catalogue routes and check the leagues and bookmakers your plan returns.
3. Rebuild saved events, markets and outcomes from v1 identifiers.
4. Run v1 beside your current integration and compare the prices, results and history your product relies on.
5. Switch production traffic once you are satisfied, before v2 is retired.

Timeline

Dates are not set yet. We will confirm each one with existing customers before it takes effect.

Getting help

Email [email protected] with your account email address and the request you are moving. Never send an API key or card details to support. Lost a key? Rotate it on your account page; the replacement is shown once.