Italian bookmaker odds,
in one API

GET /api/v1/mock/odds no key needed

Every endpoint has a twin under /api/v1/mock/ that answers right now, with no signup and no quota consumed: same response shape, same parameters, same strict validation as the real feed. The prices are synthetic — mock: true, header X-Odss-Mock: 1, ids prefixed mock_ — they are there to write and test your code, not to bet on.

curl "https://odss-api.com/api/v1/mock/odds?sport=calcio&limit=3"

Available: /mock/odds · /mock/odds/history · /mock/sports · /mock/bookmakers · /mock/leagues · /mock/status · /mock/stream (SSE). The seed parameter makes the payload reproducible: use it in CI instead of burning quota on every run.

On the REAL feed these are public with no key too: /api/v1/leagues, /api/v1/coverage and /api/v1/status.

GET /api/v1/odds example

curl "https://odss-api.com/api/v1/odds?sport=calcio&league=serie%20a&limit=5" \
  -H "x-api-key: odss_live_..."

const r = await fetch(
  "https://odss-api.com/api/v1/odds?sport=calcio&league=serie%20a&limit=5",
  { headers: { "x-api-key": "odss_live_..." } }
);
const { count, odds } = await r.json();

import requests
r = requests.get(
    "https://odss-api.com/api/v1/odds",
    params={"sport": "calcio", "league": "serie a", "limit": 5},
    headers={"x-api-key": "odss_live_..."},
)
data = r.json()  # { count, offset, returned, state, odds: [...] }

GET /api/v1/odds

Current cross-book odds, grouped by event, market and line. Each record lists the bookmakers with their outcomes and the timestamp of their last update.

Parameters

Response fields

Pagination

Repeat the call increasing offset by returned, as long as offset + returned < count. The board is live: count may shift slightly between pages.

GET /api/v1/odds?sport=calcio&limit=1000&offset=0
GET /api/v1/odds?sport=calcio&limit=1000&offset=1000
# … while offset + returned < count

GET /api/v1/sports

The sports currently available in the feed (the values for the sport parameter).

GET /api/v1/bookmakers

The bookmakers active in the feed, with country (ISO 3166-1 alpha-2 code of the licensing country — IT, GB, US, SE… — or world when none is attributed), playable_it (true only for books holding an Italian ADM licence, i.e. playable from Italy: false for every other book in the feed, from sharp references like Pinnacle to the international brands), is_exchange (commission on winnings) and source (direct when we read the book ourselves, partner_feed when its prices reach us through a third-party data provider).

GET /api/v1/leagues public, no key

The current schedule, aggregated: for each sport the priced leagues, with event and bookmaker counts. Useful to discover values for the league filter.

GET /api/v1/stream Pro and Enterprise

Server-Sent Events: a hello event on connect, then odds events with the CHANGED records (same schema as /odds, each with its own state) and the removed ones, within ~10 seconds of the engine detecting them — no polling. Optional sport and state (prematch|live|all) parameters; initial snapshot via GET /odds?state=…. Data cadence stays the engine's (per-book freshness measured on the status page, including the books that come from a third-party data provider under a contractual licence): the stream removes polling latency, last_update is authoritative. Max 3 concurrent streams; the connection counts as 1 quota request.

GET /api/v1/odds/history

Odds change history for an event: one row every time a bookmaker moves a price on a group. Filters event_id (required), book, market, from/to (ISO), limit. Newest first: for a started event the first row is its closing line. Honours the key scope.

curl "https://odss-api.com/api/v1/odds/history?event_id=a3f9c1e07b2d4865&book=snai" \
  -H "x-api-key: odss_live_..."

GET /api/v1/middles

Over/Under middles computed from the current feed: OVER on a low line at one book, UNDER on a high line at another. If the total lands inside the window both bets win. Fields middle_window, hit_return_pct, miss_return_pct, safe (no loss even when it misses). Filters: sport, min_return, safe, limit.

Freshness rule: a price older than stale_after_seconds (900s by default) stays in /odds responses with its last_update, but is never paired into a middle: a stale leg probably no longer exists on the bookmaker site. The applied threshold and the number of discarded legs are in the response.

curl "https://odss-api.com/api/v1/middles?sport=calcio&safe=true" \
  -H "x-api-key: odss_live_..."

GET /api/v1/coverage public, no key

How many bookmaker brands have a valid price in the current feed, per region (Italy, USA, UK, world). It does not match the number of entries in /api/v1/bookmakers: that endpoint lists the queryable keys, where dedicated market lanes (e.g. <brand>-corners) count on their own, while here they are folded under the brand.

GET /api/v1/coverage/matrix public, no key

For every bookmaker, sport by sport: the normalized markets it prices right now, with the lines seen. It exists to keep apart three things a flat list confuses. A market not listed under an attivo bookmaker is a structural absence: that book does not price it, and tomorrow will be the same. The bookmakers in live_only_bookmakers have rows but not in the pre-match lane, so about their pre-match markets this says nothing; if a feed lane did not answer, incomplete_lanes names it and the coverage is partial, not absent. And a market the engine cannot map with certainty is never guessed: it goes out as other:<label> and here is only counted (other_markets), because two books label the same thing differently and comparing those labels would be wrong — the ones many books spell identically are in other_markets_common. Scope prematch, recomputed at most every 10 minutes (generated_at).

POST /api/mcp MCP

MCP server (JSON-RPC 2.0) for AI agents and connectors (Claude, ChatGPT…). Auth with the same key (Authorization: Bearer odss_live_… or x-api-key). Tools: get_odds (with state=live), list_sports, list_bookmakers, list_leagues. Only tools/call uses quota; the handshake is free. Stateless: every request is self-contained.

curl -X POST https://odss-api.com/api/mcp \
  -H "Authorization: Bearer odss_live_..." -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_odds","arguments":{"sport":"calcio","state":"live","limit":5}}}'

Webhook Enterprise

Register an https URL from the dashboard or via API — POST /api/account/webhooks with your account session (body {url, sport?, state?}; the secret is shown once, max 20 per account) — and receive odds changes via POST: same {changed, removed} payload as the stream. Each delivery is signed: X-Odss-Signature: t=<unix>,v1=<hex> = HMAC-SHA256 of «{timestamp}.{body}» with the webhook secret (verify it, reject old timestamps). https only, redirects not followed; endpoints that repeatedly fail auto-disable. Respond 2xx. One delivery can arrive as several consecutive POSTs, each signed on its own and numbered by the X-Odss-Page: page/total header: every body carries page, pages, changed_total and removed_total, so the first page already tells you how much is coming. Don't rate-limit the endpoint: a rejected page stops the ones after it.

Limits, headers and errors

Every authenticated response includes X-RateLimit-Limit (your plan's monthly quota), X-RateLimit-Remaining and X-RateLimit-Reset (unix seconds when the window reopens; on the monthly-quota 429 the same instant is in the body as retry_at). The quota covers a 30-day window that starts with the first request of the period: when it ends, the counter resets and a new window starts with the next request.

Parameters: no silent failures

On every /api/v1 endpoint a parameter we don't recognize is never ignored: if you write bookmaker instead of bookmakers you get a 400 with the wrong name, the list of the ones allowed on that endpoint and, if it's a typo, a suggestion for the right name. The comparison is exact: even Sport with a capital letter is rejected. The catalog endpoints (/sports, /bookmakers, /leagues, /coverage, /status) accept no parameters. We prefer an error right away over a 200 response with unfiltered data that looks correct: the 400 is deterministic, it should be fixed rather than retried, and it does not use quota.

The same rule applies to the tool arguments on the MCP server (POST /api/mcp): a name that doesn't exist, or a wrong type such as a list where a CSV string is expected, gets a JSON-RPC -32602 error instead of being ignored. The error.data field carries the allowed names, so the agent corrects itself.

curl "https://odss-api.com/api/v1/odds?bookmaker=snai" -H "x-api-key: odss_live_..."

HTTP/1.1 400 Bad Request
{
  "error": "Parametro sconosciuto: \"bookmaker\" (forse intendevi \"bookmakers\"?). Ammessi su questo endpoint: after, bookmakers, changed_since, commence_from, commence_to, content, country, event_id, format, league, limit, market, offset, playable_it, player, sport, state"
}

Machine-readable · contract & agents

To generate clients, SDKs or use the API from an AI agent: the OpenAPI 3.1 contract and a concise LLM guide are public and always in sync.

Usage license

Internal use (models, bots, analysis, backtests) is included in every plan. Redistributing the data — e.g. showing it to your product's end users — requires the Display Redistribution licence (Enterprise add-on, +€120/month), which covers display only. Creating, powering or commercialising surebet/arbitrage services, value betting or equivalents requires the Surebet API instead, the plan that includes the licence to resell the computed surebets: €950/month + VAT, from the site. Redistributing the API or the raw data stays outside every plan: for that, write to [email protected].