Italian ADM, international and exchange bookmakers 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) · /mock/ticker (one frame of sample 1X2 odds every 5 s, no parameters). 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, /api/v1/status and /api/v1/pulse.

First call in 3 steps

1. Create a key Sign up and generate a key in the dashboard. The Free plan is forever.
2. List sports Verify the key with a call to /sports.
3. Get odds Call /odds with sport and market: you get cross-book odds.

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, each with these fields.

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: only the changed and removed records arrive, no polling. With state=live, live usually arrives within 10-30 seconds (measured median about 15 s). Today's limit, measured on 8 October 2026: with state=all a full pre-match round weighs hundreds of MB and the connection drops before it is received; the stream carried no change 79% of the time, with a resync about every 12 minutes. Pre-match only arrives with narrow filters (sport, market, league), in waves, when the served snapshot is renewed. We are rewriting the delivery into small pages with backpressure; until then, for all of the pre-match use the paginated snapshot of /odds.

GET /api/v1/odds/history

Not active yet. Capture is switched off today: every call answers 200 with count: 0 and history_enabled: false, and counts against your quota. Once active: 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.

Limits of safe, today: some market families are not yet keyed by unit (in tennis and volleyball a set total can sit next to a games or points total), some 'Home - Away' pseudo-events of one platform are served like matches, and two matches with the same name can share an event_id. In those cases safe: true is not a real middle: before acting, check that both legs are the same match, the same unit and the same start time. The response says so in the safe_note field.

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 matches the entries of /api/v1/bookmakers: both count an operator once, with its dedicated market lanes (e.g. <brand>-corners) under the brand; in /bookmakers the keys its prices are served with are in feed_keys.

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).

GET /api/v1/pulse public, no key

The feed heartbeat, aggregate numbers only (no prices, no book names): it is what the pages of this site poll on their own. No parameters, Cache-Control: public, max-age=5, its own per-IP limit (60 per minute).

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 and receive odds changes via POST, with the same {changed, removed} payload as the stream.

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.

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"
}

Resources for machines and 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. Redistributing the API or the raw data stays outside every plan: for that, write to [email protected].