# odss-api

> JSON API of pre-match and in-play (live) sports betting odds from 40+ bookmakers, including the Italian ADM books that global odds APIs don't carry, plus bet365, Betfair Exchange and Pinnacle. Base URL: https://odss-api.com/api/v1 · Auth: `x-api-key` header.

Odds are normalized into a stable JSON schema. Each event carries a deterministic `event_id` (shared by all markets of the same fixture) and each bookmaker quote carries a `last_update` (ISO 8601). Every record carries a `state` (`prematch` or `live`); live records also carry the current `score` and `minute`. Pagination via `offset`/`limit`; discovery endpoints (`/sports`, `/bookmakers`, `/leagues`, `/coverage`) are available, `/leagues` and `/coverage` without a key. Enterprise plans add a Server-Sent Events stream at `/api/v1/stream` (odds changes, not full snapshots). Data cadence is the engine's: Italian books run on a continuous cycle — the real, measured per-book freshness distribution (p50/p95 over 24h) is public at `/api/v1/status`; bet365/Betfair come via partner feeds. Judge each quote by its `last_update`.

## Endpoints
- [GET /api/v1/odds](https://odss-api.com/#docs): cross-book odds by event/market; params `sport`, `market`, `league`, `bookmakers`, `event_id`, `state` (prematch|live|all), `limit`, `offset`. Use `state=live` for in-play odds with current score/minute. Keys can be scoped to a single feed state (prematch-only or live-only): a `state` outside the key scope returns 403, and `all` degrades to the allowed state (the response `state` field reports what was actually served). Requires `x-api-key`.
- [GET /api/v1/sports](https://odss-api.com/#docs): sport keys currently in the feed. Requires `x-api-key`.
- [GET /api/v1/bookmakers](https://odss-api.com/#docs): active bookmakers with `country`, `playable_it`, `is_exchange`. Requires `x-api-key`.
- [GET /api/v1/leagues](https://odss-api.com/#docs): current schedule, sport → leagues with event/book counts. Public, no key.
- [GET /api/v1/coverage](https://odss-api.com/#docs): bookmaker catalog count per region. Public, no key.
- [GET /api/v1/status](https://odss-api.com/status): operational status + REAL freshness distribution (per-book records, current staleness, p50/p95 over 24h, ok/error). Public, no key. Human view at /status.
- [GET /api/v1/stream](https://odss-api.com/#docs): SSE odds-change stream; params `sport`, `state` (prematch|live|all; same key-scope rules as /odds: out-of-scope state → 403, `all` degrades). Enterprise only.
- [POST /api/mcp](https://odss-api.com/#docs): MCP server (JSON-RPC 2.0) for AI agents and connectors. Auth `Authorization: Bearer odss_live_…`. Tools: `get_odds` (with state=live), `list_sports`, `list_bookmakers`, `list_leagues`. Only `tools/call` counts against quota; the handshake is free.
- Outgoing webhooks (Enterprise): register a delivery URL and receive odds-change POSTs (`{changed, removed}`) signed `HMAC-SHA256(secret, "{timestamp}.{body}")` in the `X-Odss-Signature` header. Managed from the dashboard (Enterprise section) or via the account API: `GET/POST /api/account/webhooks` (body: `{url, sport?, state?}`; the secret is returned once at registration), `POST /api/account/webhooks/{id}/delete`, `POST /api/account/webhooks/{id}/enable`. Auth: `Authorization: Bearer <session token>` from `/api/account/login`. Max 20 webhooks per account; endpoints that repeatedly fail are auto-disabled.

## Reference
- [OpenAPI spec](https://odss-api.com/openapi.json): machine-readable contract (OpenAPI 3.1).
- [Postman collection](https://odss-api.com/postman_collection.json): ready-to-import request collection.
- [API docs](https://odss-api.com/#docs): human documentation, parameters, examples.
- [Pricing](https://odss-api.com/#prezzi): Free, Starter, Pro and a configurable Enterprise plan.

## Optional
- [Terms of service](https://odss-api.com/#): usage license; internal use included, redistribution to end users requires the SaaS/Enterprise license.
- [Contact](mailto:info@praxis3.it): PRAXIS 3 S.r.l., VAT IT01434870661.