# OddsIntel Odds API

> Per-book football odds with read age on every price. Books are served only while sold and passing their SLO; Cache-Control: no-store on every response.

Football only. JSON over HTTPS, version 1.0.0-beta. Every price carries its read age (read_age_s) and a stale flag. 18+ · for businesses · not betting advice.

## Base URL and authentication

- Base URL: https://odds.oddsintel.app (paths below start with /v1/odds)
- Send the key as `Authorization: Bearer oid_...`. Free key by e-mail: https://odds.oddsintel.app/key
- Keep the key on a server; never put it in a web page or a downloadable app.
- Sandbox keys answer once the first recorded day exists; until then they return 503 sandbox_unavailable.

## Endpoints

- GET /v1/odds/books — Serving books (and removed ones), with family; Free keys see in_your_plan
- GET /v1/odds/bulk/{kind}/{name} — A UTC day of per-book closes or price history as one gzip CSV (Pro+), plus its gaps
- GET /v1/odds/changes — Price changes since a time / after a cursor (Starter+); a cursor stays valid 7 days
- GET /v1/odds/closes — Per-book closes for a UTC kick-off day, with read_age_at_ko_s and close_quality (Pro+)
- GET /v1/odds/competitions — Competitions the serving books price (next 7 days): books and events per competition
- GET /v1/odds/events — Events by kick-off (keyset paging)
- GET /v1/odds/history — One event's price changes per book inside the plan's history window (Pro+)
- GET /v1/odds/markets — Markets the serving books price (next 7 days): definition, books, events
- GET /v1/odds/prices — Many events' current prices per book in one call (≤ 200 events or < 1 MB per page)
- GET /v1/odds/webhook — This key's webhook + recent deliveries
- PUT /v1/odds/webhook — Register / replace this key's https webhook; answers the signing secret once
- DELETE /v1/odds/webhook — Remove this key's webhook
- POST /v1/odds/webhook/test — Queue a signed ping notice
- GET /v1/odds/{event_id} — One event: every serving book's current price per line, with read_age_s and stale

Errors are application/problem+json with a stable `code`. A 503 means we serve nothing rather than something doubtful: retry after Retry-After. Send an ETag back as If-None-Match: an unchanged answer is a 304 that costs no quota.

## Docs

- [API reference](https://odds.oddsintel.app/docs/reference): every endpoint, parameter and response, with a try-it console
- [OpenAPI 3.1 spec](https://odds.oddsintel.app/openapi.json): machine-readable, for code generators
- [Quick start: curl, Python, JavaScript](https://odds.oddsintel.app/docs/quickstart): Get a free key on odds.oddsintel.app (keys). It arrives by e-mail in a minute.
- [Keys and your account](https://odds.oddsintel.app/docs/keys): Get a free key. On odds.oddsintel.app: name, e-mail, a line on what you will build, tick the terms. The key is e-mailed at once and only to that address, so…
- [Books](https://odds.oddsintel.app/docs/books): GET /v1/odds/books is the book list, at request time, for your key. This page explains it; it does not copy it, and it names no book: the list, each book's…
- [Sandbox](https://odds.oddsintel.app/docs/sandbox): A Sandbox key answers every /v1/odds/* endpoint, in the live schema, from one recorded moment of the live API: the board at that moment (with the read ages…
- [Status](https://odds.oddsintel.app/docs/status): The Odds API's line on the public status page (status.oddsintel.app).
- [Changelog](https://odds.oddsintel.app/changelog)