# Moving to v1

SockOdds API v1 replaces v2. It is a new contract built on our own identifiers and the prices we record ourselves. This page sets out what changes for an existing integration and how to plan the move.

## 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](https://sockodds.com/account/).

## 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](https://sockodds.com/docs/#listEvents) by league and start time, then store the returned identifiers.

If you already hold official event ids, [/v1/events/lookup](https://sockodds.com/docs/#lookupEvents) 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.
| Object | Identifier |
| Event | `ev_` then 12 lowercase letters and digits |
| Player | `pl_` then 12 lowercase letters and digits |
| Market, within an event | `mk_` then 16 lowercase letters and digits |
| Outcome, within a market | `oc_` then 16 lowercase letters and digits |

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.
| To do this | Use |
| List the sports we cover | [GET /v1/sports](https://sockodds.com/docs/#listSports) |
| List leagues, optionally for one sport | [GET /v1/leagues](https://sockodds.com/docs/#listLeagues) |
| List bookmakers, optionally by region | [GET /v1/bookmakers](https://sockodds.com/docs/#listBookmakers) |
| List markets and the sides each offers | [GET /v1/markets](https://sockodds.com/docs/#listMarkets) |
| List teams in a league | [GET /v1/teams](https://sockodds.com/docs/#listTeams) |
| List players, by league or team | [GET /v1/players](https://sockodds.com/docs/#listPlayers) |
| Find events by league and start time | [GET /v1/events](https://sockodds.com/docs/#listEvents) |
| Find our event from an ESPN event id, an AFLW match id or a Rugby League World Cup match id | [GET /v1/events/lookup](https://sockodds.com/docs/#lookupEvents) |
| Read one event and its participants | [GET /v1/events/{event_id}](https://sockodds.com/docs/#getEvent) |
| Read current prices for one event | [GET /v1/events/{event_id}/odds](https://sockodds.com/docs/#getEventOdds) |
| Read current prices across a league | [GET /v1/odds](https://sockodds.com/docs/#listOdds) |
| Receive prices as they refresh | [WebSocket /v1/stream/odds](https://sockodds.com/docs/#streamOdds) |
| Read recorded price changes for an event | [GET /v1/odds/history](https://sockodds.com/docs/#listOddsHistory) |
| List whole days of recorded history to download | [GET /v1/history/files](https://sockodds.com/docs/#listHistoryFiles) |
| Download one league's day of history as a Parquet file | [GET /v1/history/files/{league}/{day}](https://sockodds.com/docs/#getHistoryFile) |
| Read graded results | [GET /v1/results](https://sockodds.com/docs/#listResults) |

## 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](https://sockodds.com/docs/#streamOdds) 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](https://sockodds.com/docs/history/#how-far-back-it-goes) 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
- Download the [OpenAPI contract](https://sockodds.com/openapi.json) and read the [reference](https://sockodds.com/docs/).
- Send your existing key as a bearer token to the catalogue routes and check the leagues and bookmakers your plan returns.
- Rebuild saved events, markets and outcomes from v1 identifiers.
- Run v1 beside your current integration and compare the prices, results and history your product relies on.
- 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.
| Stage | What happens | When |
| Preview | v1 is available for testing. v2 keeps working. | Now |
| Running side by side | v1 opens to all customers. v2 keeps working while you move. | To be confirmed |
| v2 retired | Every v2 route answers `410 Gone`. | To be confirmed |

## Getting help

Email support@sockodds.com 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](https://sockodds.com/account/); the replacement is shown once.