{"openapi":"3.1.0","info":{"title":"UK Odds API","description":"Pre-match **football** fixtures and odds. Browse events, fetch the latest odds (single, best, or batch), and find 2-way arbitrage opportunities.\n\n### Quickstart\n\n1) List events: `GET /v1/football/events?schedule_date=YYYY-MM-DD`  \n2) Optional: discover markets on an event: `GET /v1/football/events/{event_id}/markets`  \n3) Get odds: `GET /v1/football/events/{event_id}/odds` (or best odds: `/odds/best`)  \n4) Get arbitrage: `GET /v1/football/arbitrage?date=YYYY-MM-DD` (or event: `/events/{event_id}/arbitrage`)  \n\n### Authentication\n\nSend **`X-Api-Key`** on `/v1/...` requests when required.\n\n### Rate limits\n\nWhen rate limits apply, responses include `X-RateLimit-*` headers. When exceeded you’ll get **429** with `Retry-After`.\n\n### Caching\n\nMany endpoints return `ETag`. Send `If-None-Match` to get **304 Not Modified**. `X-Data-Captured-At` tells you when the odds snapshot was captured.\n\n### Errors\n\nErrors use a consistent shape:\n\n```json\n{\"detail\":\"human-readable message\"}\n```\n\n### Odds format\n\nOdds are **decimal** by default. On odds routes, set **`odds_format`** to `fractional` or `american`.","version":"0.1.0"},"servers":[{"url":"https://api.ukoddsapi.com","description":"Public API base URL"}],"paths":{"/v1/health":{"get":{"tags":["reference"],"summary":"Health check","description":"Public liveness probe for load balancers and CI deploy checks. Does not require an API key and performs no writes.","operationId":"v1_health_v1_health_get","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response V1 Health V1 Health Get"},"examples":{"sample":{"summary":"OK","value":{"schema_version":"1.0","status":"ok","version":"0.0.0"}}}}}}}}},"/v1/sports":{"get":{"tags":["reference"],"summary":"List supported sports","description":"Sports currently available through the API.","operationId":"list_sports_v1_sports_get","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response List Sports V1 Sports Get"},"examples":{"sample":{"summary":"Supported sports","value":{"schema_version":"1.0","sports":[{"key":"football","name":"Football (Soccer)","active":true}]}}}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/auth/verify":{"get":{"tags":["reference"],"summary":"Verify API key","description":"Returns 200 when your `X-Api-Key` is valid. Swagger's **Authorize** button does not validate keys until a request runs.","operationId":"auth_verify_v1_auth_verify_get","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Auth Verify V1 Auth Verify Get"},"examples":{"sample":{"summary":"Key is valid","value":{"schema_version":"1.0","ok":true}}}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/bookmakers":{"get":{"tags":["reference"],"summary":"List supported bookmakers","description":"Bookmakers that may appear in odds responses. `bookmaker_code` is the stable ID for filtering.","operationId":"list_bookmakers_v1_bookmakers_get","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response List Bookmakers V1 Bookmakers Get"},"examples":{"sample":{"summary":"Bookmaker catalog (sample)","value":{"schema_version":"1.0","count":4,"bookmakers":[{"bookmaker_code":"UO001","name":"10Bet","type":"sportsbook","region":"uk"},{"bookmaker_code":"UO004","name":"Bet365","type":"sportsbook","region":"uk"},{"bookmaker_code":"UO006","name":"Betfair","type":"exchange","region":"uk"},{"bookmaker_code":"UO034","name":"IvyBet","type":"sportsbook","region":"uk"}]}}}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/football/leagues":{"get":{"tags":["reference"],"summary":"List supported football leagues","description":"Football leagues from the coverage catalog. Use the returned `name` as a filter on `GET /v1/football/events`.","operationId":"list_football_leagues_v1_football_leagues_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional country code slug, e.g. `england` or `italy`.","title":"Country"},"description":"Optional country code slug, e.g. `england` or `italy`."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based).","default":1,"title":"Page"},"description":"Page number (1-based)."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Results per page (max 200).","default":50,"title":"Per Page"},"description":"Results per page (max 200)."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Football Leagues V1 Football Leagues Get"},"examples":{"sample":{"summary":"Supported football leagues","value":{"schema_version":"1.0","sport":"football","count":2,"leagues":[{"name":"Premier League","path":"/football/english/premier-league","country_code":"england","country_name":"England","competition_type":"league","gender":"mens","level":"senior"},{"name":"Serie A","path":"/football/italy/serie-a","country_code":"italy","country_name":"Italy","competition_type":"league","gender":"mens","level":"senior"}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/countries":{"get":{"tags":["reference"],"summary":"List supported football countries","description":"Countries/territories in the football coverage catalog.","operationId":"list_football_countries_v1_football_countries_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based).","default":1,"title":"Page"},"description":"Page number (1-based)."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Results per page (max 200).","default":50,"title":"Per Page"},"description":"Results per page (max 200)."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Football Countries V1 Football Countries Get"},"examples":{"sample":{"summary":"Supported football countries","value":{"schema_version":"1.0","sport":"football","count":2,"countries":[{"country_code":"england","country_name":"England","competition_count":14,"league_count":10},{"country_code":"italy","country_name":"Italy","competition_count":8,"league_count":6}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/competitions":{"get":{"tags":["reference"],"summary":"List football competitions (coverage)","description":"Competition coverage catalog. Use filters (e.g. `competition_type=league`). Use `view=tree` for a nested hierarchy.","operationId":"list_football_competitions_v1_football_competitions_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"view","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"View"}},{"name":"competition_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Competition Type"}},{"name":"gender","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender"}},{"name":"level","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Level"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based). Ignored for `view=tree`.","default":1,"title":"Page"},"description":"Page number (1-based). Ignored for `view=tree`."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Results per page (max 200). Ignored for `view=tree`.","default":50,"title":"Per Page"},"description":"Results per page (max 200). Ignored for `view=tree`."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Football Competitions V1 Football Competitions Get"},"examples":{"list":{"summary":"Flat list (default)","value":{"schema_version":"1.0","sport":"football","count":1,"competitions":[{"path":"/football/english/premier-league","name":"Premier League","competition_type":"league","gender":"mens","level":"senior","section_names":["All European Competitions"],"category_names":["English"],"updated_at":"2026-04-21T00:00:00Z"}]}},"tree":{"summary":"Coverage hierarchy (view=tree)","value":{"schema_version":"1.0","sport":"football","updated_at_utc":"2026-04-21T00:00:00Z","summary":{"section_count":2,"category_count":5,"competitions_listed":20,"unique_competitions":18},"sections":[{"section_name":"Top Competitions","direct_competitions":[{"name":"Champions League","path":"/football/champions-league","competition_type":"cup","gender":"mens","level":"senior"}],"categories":[]}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/markets":{"get":{"tags":["football"],"summary":"Football market catalog","description":"Market catalog used by `market_key` filters. Optional `group` and `package` filters.","operationId":"list_markets_v1_football_markets_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"group","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional market group filter, e.g. `player-markets`.","title":"Group"},"description":"Optional market group filter, e.g. `player-markets`."},{"name":"package","in":"query","required":false,"schema":{"enum":["full","core"],"type":"string","description":"`core` or `full`.","default":"full","title":"Package"},"description":"`core` or `full`."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Markets V1 Football Markets Get"},"examples":{"sample":{"summary":"Global football market catalog","value":{"schema_version":"1.0","sport":"football","count":3,"groups":["goals","main","scorer"],"markets":[{"key":"winner","name":"Win Market","group":"main","package":"core"},{"key":"anytime-scorer","name":"Anytime Goalscorer","group":"scorer","package":"full"},{"key":"total-goals-over-under","name":"Total Goals Over/Under","group":"goals","package":"core"}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/account/me":{"get":{"tags":["account"],"summary":"Current API key profile","description":"Returns non-secret metadata for the **same** `X-Api-Key` you use on `/v1/...`. Intended for customer dashboards — not for operators (use `/admin` on the API host for ops).","operationId":"account_me_v1_account_me_get","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Account Me V1 Account Me Get"},"examples":{"sample":{"summary":"Customer key profile","value":{"schema_version":"1.0","account_type":"customer","key_id":"key_a1b2c3d4e5f67890","key_prefix":"uko_live_a1b2c3d4","name":"Acme Trading","tier":"pro","plan_id":"pro","created_at":"2026-04-01T10:00:00Z","last_used_at":"2026-04-22T08:15:00Z","active":true,"rate_limits":{"requests_per_hour":5000,"burst_requests_per_minute":84,"requests_per_day":120000,"unlimited":false}}}}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/football/events":{"get":{"tags":["football"],"summary":"List football events","description":"Events by `schedule_date` or `from`+`to`. Optional `upcoming` filters by `kickoff_utc` vs server UTC now. Requires `X-Api-Key` but does not consume usage quota.","operationId":"list_events_v1_football_events_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"schedule_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Single football calendar day (YYYY-MM-DD). Exclusive with `from`/`to`.","title":"Schedule Date"},"description":"Single football calendar day (YYYY-MM-DD). Exclusive with `from`/`to`."},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"Start of date range (YYYY-MM-DD, inclusive).","title":"From"},"description":"Start of date range (YYYY-MM-DD, inclusive)."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"description":"End of date range (YYYY-MM-DD, inclusive).","title":"To"},"description":"End of date range (YYYY-MM-DD, inclusive)."},{"name":"league","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Case-insensitive league name substring filter (e.g. `premier league`).","title":"League"},"description":"Case-insensitive league name substring filter (e.g. `premier league`)."},{"name":"has_odds","in":"query","required":false,"schema":{"type":"boolean","description":"When true, return only events that currently have at least one odds market.","default":false,"title":"Has Odds"},"description":"When true, return only events that currently have at least one odds market."},{"name":"upcoming","in":"query","required":false,"schema":{"type":"boolean","description":"When true, only events with `kickoff_utc` strictly after server time (UTC).","default":false,"title":"Upcoming"},"description":"When true, only events with `kickoff_utc` strictly after server time (UTC)."},{"name":"tz","in":"query","required":false,"schema":{"type":"string","description":"Timezone for the `kickoff` field. Defaults to UK time (`Europe/London`). Use `UTC` for UTC.","default":"Europe/London","title":"Tz"},"description":"Timezone for the `kickoff` field. Defaults to UK time (`Europe/London`). Use `UTC` for UTC."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based).","default":1,"title":"Page"},"description":"Page number (1-based)."},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Results per page (max 200).","default":50,"title":"Per Page"},"description":"Results per page (max 200)."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Events V1 Football Events Get"},"examples":{"sample":{"summary":"Paginated football events","value":{"schema_version":"1.0","sport":"football","from":"2026-04-20","to":"2026-04-20","count":1,"meta":{"page":1,"per_page":50,"total":23,"total_pages":1},"events":[{"event_id":"evt_06ce81ef6bf857d5f0b9eb54cc13","league_name":"Brazilian Serie B","home_team":"Novorizontino","away_team":"Athletic Club MG","kickoff_utc":"2026-04-19T23:00:00Z","schedule_date":"2026-04-20","markets_with_odds":64,"unique_bookmaker_codes":25,"sport":"football"}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/arbitrage/markets":{"get":{"tags":["football"],"summary":"Football arbitrage supported markets","description":"Market types supported by the football arbitrage endpoints.","operationId":"list_arbitrage_markets_v1_football_arbitrage_markets_get","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response List Arbitrage Markets V1 Football Arbitrage Markets Get"},"examples":{"sample":{"summary":"Football arbitrage market scope","value":{"schema_version":"1.0","sport":"football","type":"2-way","min_profit_default":0.5,"markets":["Total Corners","Total Home Goals","Total Away Goals","Total Home Corners","Total Away Corners","Total Goals Over/Under","1st Half Total Goals","2nd Half Total Goals","1st Half Total Corners","2nd Half Total Corners","Total Bookings Over/Under","Total Cards Over/Under","Player Shots On Target"]}}}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/football/arbitrage":{"get":{"tags":["football"],"summary":"Active football arbitrage opportunities for a day","description":"2-way arbitrage opportunities for fixtures on a schedule day. Use `total_stake` and `round_to` for stake amounts.","operationId":"list_arbitrage_v1_football_arbitrage_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Football schedule_date (Europe/London YYYY-MM-DD). Use dates returned by `/v1/football/events`.","title":"Date"},"description":"Football schedule_date (Europe/London YYYY-MM-DD). Use dates returned by `/v1/football/events`."},{"name":"min_profit","in":"query","required":false,"schema":{"type":"number","description":"Minimum profit percentage to return.","default":0.5,"title":"Min Profit"},"description":"Minimum profit percentage to return."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum arbitrages to return after sorting by profit.","default":100,"title":"Limit"},"description":"Maximum arbitrages to return after sorting by profit."},{"name":"total_stake","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0.01},{"type":"null"}],"description":"Optional: total stake amount (GBP) to compute ready-to-bet stake splits.","title":"Total Stake"},"description":"Optional: total stake amount (GBP) to compute ready-to-bet stake splits."},{"name":"round_to","in":"query","required":false,"schema":{"type":"integer","maximum":5,"minimum":0,"description":"Optional rounding for computed stake amounts: 0 (none), 1 (nearest £1), 5 (nearest £5).","default":0,"title":"Round To"},"description":"Optional rounding for computed stake amounts: 0 (none), 1 (nearest £1), 5 (nearest £5)."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional market name substring filter.","title":"Market"},"description":"Optional market name substring filter."},{"name":"market_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional stable market key from `/v1/football/markets`.","title":"Market Key"},"description":"Optional stable market key from `/v1/football/markets`."},{"name":"bookmakers","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional comma-separated bookmaker names.","title":"Bookmakers"},"description":"Optional comma-separated bookmaker names."},{"name":"bookmaker_codes","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional comma-separated public bookmaker_code values.","title":"Bookmaker Codes"},"description":"Optional comma-separated public bookmaker_code values."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Arbitrage V1 Football Arbitrage Get"},"examples":{"sample":{"summary":"Daily football arbitrage feed","value":{"schema_version":"1.0","sport":"football","date":"2026-04-25","count":1,"min_profit":0.5,"arbitrages":[{"event_id":"evt_cardiff_northampton_2026_04_25","event_title":"Cardiff City vs Northampton","competition":"English League One","home_team":"Cardiff City","away_team":"Northampton","schedule_date":"2026-04-25","kickoff_utc":"2026-04-25T14:00:00Z","captured_at":"2026-04-25T09:04:09.873881Z","market_id":999,"market_name":"Total Away Corners","market_group":"corners","market_type":"2way","description":"Over 1.5 vs Under 1.5","type":"2-way","profit_percentage":7.55,"implied_probability":92.98,"legs":[{"selection":"Over 1.5","line":"1.5","odds":1.5,"bookmaker_code":"UO028","bookmaker_name":"William Hill","bookmaker_type":"sportsbook","stake_percentage":71.7},{"selection":"Under 1.5","line":"1.5","odds":3.8,"bookmaker_code":"UO013","bookmaker_name":"BoyleSports","bookmaker_type":"sportsbook","stake_percentage":28.3}],"stake_plan":{"total_stake":300.0,"currency":"GBP","round_to":1,"legs":[{"bookmaker_code":"UO028","bookmaker_name":"William Hill","selection":"Over 1.5","odds":1.5,"stake_amount":215.09,"stake_amount_final":215.0,"return_amount":322.5},{"bookmaker_code":"UO013","bookmaker_name":"BoyleSports","selection":"Under 1.5","odds":3.8,"stake_amount":84.91,"stake_amount_final":85.0,"return_amount":323.0}],"sure_return":322.5,"sure_profit":22.5,"roi_percent":7.5}}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/events/{event_id}/arbitrage":{"get":{"tags":["football"],"summary":"Active arbitrage opportunities for one football event","description":"2-way arbitrage opportunities for a single event using the latest odds.","operationId":"get_event_arbitrage_v1_football_events__event_id__arbitrage_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","title":"Event Id"}},{"name":"min_profit","in":"query","required":false,"schema":{"type":"number","description":"Minimum profit percentage to return.","default":0.5,"title":"Min Profit"},"description":"Minimum profit percentage to return."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Maximum arbitrages to return after sorting by profit.","default":50,"title":"Limit"},"description":"Maximum arbitrages to return after sorting by profit."},{"name":"total_stake","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0.01},{"type":"null"}],"description":"Optional: total stake amount (GBP) to compute ready-to-bet stake splits.","title":"Total Stake"},"description":"Optional: total stake amount (GBP) to compute ready-to-bet stake splits."},{"name":"round_to","in":"query","required":false,"schema":{"type":"integer","maximum":5,"minimum":0,"description":"Optional rounding for computed stake amounts: 0 (none), 1 (nearest £1), 5 (nearest £5).","default":0,"title":"Round To"},"description":"Optional rounding for computed stake amounts: 0 (none), 1 (nearest £1), 5 (nearest £5)."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional market name substring filter.","title":"Market"},"description":"Optional market name substring filter."},{"name":"market_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional stable market key from `/v1/football/markets`.","title":"Market Key"},"description":"Optional stable market key from `/v1/football/markets`."},{"name":"bookmakers","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional comma-separated bookmaker names.","title":"Bookmakers"},"description":"Optional comma-separated bookmaker names."},{"name":"bookmaker_codes","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional comma-separated public bookmaker_code values.","title":"Bookmaker Codes"},"description":"Optional comma-separated public bookmaker_code values."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"title":"Response Get Event Arbitrage V1 Football Events  Event Id  Arbitrage Get"},"examples":{"sample":{"summary":"Single-event football arbitrage","value":{"schema_version":"1.0","sport":"football","date":"2026-04-25","count":1,"min_profit":0.5,"arbitrages":[{"event_id":"evt_cardiff_northampton_2026_04_25","event_title":"Cardiff City vs Northampton","competition":"English League One","home_team":"Cardiff City","away_team":"Northampton","schedule_date":"2026-04-25","kickoff_utc":"2026-04-25T14:00:00Z","captured_at":"2026-04-25T09:04:09.873881Z","market_id":999,"market_name":"Total Away Corners","market_group":"corners","market_type":"2way","description":"Over 1.5 vs Under 1.5","type":"2-way","profit_percentage":7.55,"implied_probability":92.98,"legs":[{"selection":"Over 1.5","line":"1.5","odds":1.5,"bookmaker_code":"UO028","bookmaker_name":"William Hill","bookmaker_type":"sportsbook","stake_percentage":71.7},{"selection":"Under 1.5","line":"1.5","odds":3.8,"bookmaker_code":"UO013","bookmaker_name":"BoyleSports","bookmaker_type":"sportsbook","stake_percentage":28.3}],"stake_plan":{"total_stake":300.0,"currency":"GBP","round_to":1,"legs":[{"bookmaker_code":"UO028","bookmaker_name":"William Hill","selection":"Over 1.5","odds":1.5,"stake_amount":215.09,"stake_amount_final":215.0,"return_amount":322.5},{"bookmaker_code":"UO013","bookmaker_name":"BoyleSports","selection":"Under 1.5","odds":3.8,"stake_amount":84.91,"stake_amount_final":85.0,"return_amount":323.0}],"sure_return":322.5,"sure_profit":22.5,"roi_percent":7.5}}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/events/{event_id}":{"get":{"tags":["football"],"summary":"Football event metadata","description":"`schedule_date` is the football calendar day used for filtering; `kickoff_utc` is the kickoff time in UTC. Requires `X-Api-Key` but does not consume usage quota.","operationId":"get_event_v1_football_events__event_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","title":"Event Id"}},{"name":"tz","in":"query","required":false,"schema":{"type":"string","description":"Timezone for the `kickoff` field. Defaults to UK time (`Europe/London`). Use `UTC` for UTC.","default":"Europe/London","title":"Tz"},"description":"Timezone for the `kickoff` field. Defaults to UK time (`Europe/London`). Use `UTC` for UTC."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Event V1 Football Events  Event Id  Get"},"examples":{"sample":{"summary":"Single event metadata","value":{"schema_version":"1.0","event":{"event_id":"evt_06ce81ef6bf857d5f0b9eb54cc13","league_name":"Brazilian Serie B","home_team":"Novorizontino","away_team":"Athletic Club MG","kickoff_utc":"2026-04-19T23:00:00Z","schedule_date":"2026-04-20","sport":"football"}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/events/{event_id}/markets":{"get":{"tags":["football"],"summary":"Available markets for one event","description":"Market catalog entries available for this event’s latest odds.","operationId":"get_event_markets_v1_football_events__event_id__markets_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","title":"Event Id"}},{"name":"group","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional market group filter, e.g. `player-markets`.","title":"Group"},"description":"Optional market group filter, e.g. `player-markets`."},{"name":"package","in":"query","required":false,"schema":{"enum":["full","core"],"type":"string","description":"`core` or `full`.","default":"full","title":"Package"},"description":"`core` or `full`."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"title":"Response Get Event Markets V1 Football Events  Event Id  Markets Get"},"examples":{"sample":{"summary":"Markets available on the fixture","value":{"schema_version":"1.0","sport":"football","event_id":"evt_06ce81ef6bf857d5f0b9eb54cc13","count":2,"groups":["main","player-markets"],"markets":[{"key":"winner","name":"Win Market","group":"main","package":"core","selection_count":9,"bookmaker_count":12},{"key":"player-shots","name":"Player Shots","group":"player-markets","package":"full","selection_count":60,"bookmaker_count":15}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/events/{event_id}/odds":{"get":{"tags":["football"],"summary":"Latest odds for one event","description":"Latest odds snapshot for an event. Use filters to narrow markets/bookmakers and `odds_format` to convert. Consumes usage quota: `package=core` costs 1 request; `package=full` costs 2 requests.","operationId":"get_event_odds_v1_football_events__event_id__odds_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","title":"Event Id"}},{"name":"package","in":"query","required":false,"schema":{"enum":["full","core"],"type":"string","description":"`core` or `full`.","default":"core","title":"Package"},"description":"`core` or `full`."},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Market name substring filter.","title":"Market"},"description":"Market name substring filter."},{"name":"market_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stable market key (see `GET /v1/football/markets`).","title":"Market Key"},"description":"Stable market key (see `GET /v1/football/markets`)."},{"name":"bookmakers","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated bookmaker names.","title":"Bookmakers"},"description":"Comma-separated bookmaker names."},{"name":"bookmaker_codes","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated bookmaker_code values (stable IDs).","title":"Bookmaker Codes"},"description":"Comma-separated bookmaker_code values (stable IDs)."},{"name":"odds_format","in":"query","required":false,"schema":{"enum":["decimal","fractional","american"],"type":"string","description":"Odds format: decimal | fractional | american.","default":"decimal","title":"Odds Format"},"description":"Odds format: decimal | fractional | american."},{"name":"best_only","in":"query","required":false,"schema":{"type":"boolean","description":"Return best odds per selection only.","default":false,"title":"Best Only"},"description":"Return best odds per selection only."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"title":"Response Get Event Odds V1 Football Events  Event Id  Odds Get"},"examples":{"sample":{"summary":"Odds snapshot (sample truncated)","value":{"schema_version":"1.0","event_id":"evt_06ce81ef6bf857d5f0b9eb54cc13","captured_at":"2026-04-19T18:50:47.459641Z","competition":"Brazilian Serie B","event_title":"Novorizontino vs Athletic Club MG","kickoff_utc":"2026-04-19T23:00:00Z","summary":{"markets_count":1,"bookmakers_count":2},"bookmakers":[{"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook"},{"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook"}],"markets":[{"market_id":101,"market_name":"Win Market","market_group":"main","selection_count":6,"selections":[{"selection_name":"Novorizontino","odds":2.7,"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook","status":"Active"},{"selection_name":"Draw","odds":3.1,"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook","status":"Active"},{"selection_name":"Athletic Club MG","odds":2.55,"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook","status":"Active"}]}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/events/{event_id}/odds/best":{"get":{"tags":["football"],"summary":"Best available odds per selection","description":"Shortcut for `package=full&best_only=true`.","operationId":"get_event_best_odds_v1_football_events__event_id__odds_best_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","title":"Event Id"}},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Market name substring filter.","title":"Market"},"description":"Market name substring filter."},{"name":"market_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stable market key (see `GET /v1/football/markets`).","title":"Market Key"},"description":"Stable market key (see `GET /v1/football/markets`)."},{"name":"bookmakers","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated bookmaker names.","title":"Bookmakers"},"description":"Comma-separated bookmaker names."},{"name":"bookmaker_codes","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated bookmaker_code values (stable IDs).","title":"Bookmaker Codes"},"description":"Comma-separated bookmaker_code values (stable IDs)."},{"name":"odds_format","in":"query","required":false,"schema":{"enum":["decimal","fractional","american"],"type":"string","description":"decimal | fractional | american.","default":"decimal","title":"Odds Format"},"description":"decimal | fractional | american."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"title":"Response Get Event Best Odds V1 Football Events  Event Id  Odds Best Get"},"examples":{"sample":{"summary":"Best odds per outcome (sample)","value":{"schema_version":"1.0","event_id":"evt_06ce81ef6bf857d5f0b9eb54cc13","captured_at":"2026-04-19T18:50:47.459641Z","competition":"Brazilian Serie B","event_title":"Novorizontino vs Athletic Club MG","kickoff_utc":"2026-04-19T23:00:00Z","summary":{"markets_count":1,"bookmakers_count":3},"bookmakers":[{"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook"},{"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook"},{"bookmaker_code":"UO028","bookmaker_name":"William Hill","bookmaker_type":"sportsbook"}],"markets":[{"market_id":101,"market_name":"Win Market","market_group":"main","selection_count":3,"selections":[{"selection_name":"Novorizontino","odds":2.75,"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook","status":"Active"},{"selection_name":"Draw","odds":3.1,"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook","status":"Active"},{"selection_name":"Athletic Club MG","odds":2.6,"bookmaker_code":"UO028","bookmaker_name":"William Hill","bookmaker_type":"sportsbook","status":"Active"}]}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/events/{event_id}/price-boosts":{"get":{"tags":["football"],"summary":"Price boosts for one event","description":"Returns bookmaker **price boost** offers for a fixture (same odds JSON shape as `/odds`).  \n\nRequires **Pro** or **Business**. Consumes **1** request.","operationId":"get_event_price_boosts_v1_football_events__event_id__price_boosts_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","title":"Event Id"}},{"name":"bookmakers","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated bookmaker names.","title":"Bookmakers"},"description":"Comma-separated bookmaker names."},{"name":"bookmaker_codes","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated bookmaker_code values (stable IDs).","title":"Bookmaker Codes"},"description":"Comma-separated bookmaker_code values (stable IDs)."},{"name":"odds_format","in":"query","required":false,"schema":{"enum":["decimal","fractional","american"],"type":"string","description":"Odds format: decimal | fractional | american.","default":"decimal","title":"Odds Format"},"description":"Odds format: decimal | fractional | american."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"title":"Response Get Event Price Boosts V1 Football Events  Event Id  Price Boosts Get"},"examples":{"sample":{"summary":"Price boosts snapshot","value":{"schema_version":"1.0","event_id":"evt_06ce81ef6bf857d5f0b9eb54cc13","captured_at":"2026-07-30T08:30:00Z","competition":"Brazilian Serie A","event_title":"Corinthians vs Atletico Paranaense","kickoff_utc":"2026-07-30T23:00:00Z","summary":{"markets_count":1,"bookmakers_count":2},"bookmakers":[{"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook"},{"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook"}],"markets":[{"market_id":3585748907,"market_name":"Price Boosts","market_group":"Price Boosts","selection_count":2,"selections":[{"selection_name":"Score from Outside the Box - Jesse Lingard","odds":9.5,"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook","status":"Active"},{"selection_name":"Kevin Viveros anytime goalscorer","odds":4.3333335,"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook","status":"Active"}]}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/events/{event_id}/bet-builders":{"get":{"tags":["football"],"summary":"Pre-built bet builders for one event","description":"Returns **pre-built** bet builder offers for a fixture (same odds JSON shape as `/odds`).  \n\nIncludes both **Bet Builders** and **Popular Bet Builders** when present.  \n\nThis is not custom same-game accumulator pricing for arbitrary selections.  \n\nRequires **Pro** or **Business**. Consumes **1** request.","operationId":"get_event_bet_builders_v1_football_events__event_id__bet_builders_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","title":"Event Id"}},{"name":"bookmakers","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated bookmaker names.","title":"Bookmakers"},"description":"Comma-separated bookmaker names."},{"name":"bookmaker_codes","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated bookmaker_code values (stable IDs).","title":"Bookmaker Codes"},"description":"Comma-separated bookmaker_code values (stable IDs)."},{"name":"odds_format","in":"query","required":false,"schema":{"enum":["decimal","fractional","american"],"type":"string","description":"Odds format: decimal | fractional | american.","default":"decimal","title":"Odds Format"},"description":"Odds format: decimal | fractional | american."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"title":"Response Get Event Bet Builders V1 Football Events  Event Id  Bet Builders Get"},"examples":{"sample":{"summary":"Bet builders snapshot","value":{"schema_version":"1.0","event_id":"evt_06ce81ef6bf857d5f0b9eb54cc13","captured_at":"2026-07-30T08:30:00Z","competition":"Brazilian Serie A","event_title":"Corinthians vs Atletico Paranaense","kickoff_utc":"2026-07-30T23:00:00Z","summary":{"markets_count":2,"bookmakers_count":2},"bookmakers":[{"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook"},{"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook"}],"markets":[{"market_id":3585749474,"market_name":"Popular Bet Builders","market_group":"Bet Builders","selection_count":2,"selections":[{"selection_name":"Each Team to Have 2+ Corners in Each Half","odds":4.5,"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook","status":"Active"},{"selection_name":"Corinthians to Win; Corinthians Most Corners and Athletico-PR Most Cards","odds":5.5,"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook","status":"Active"}]},{"market_id":3585708535,"market_name":"Bet Builders","market_group":"Bet Builders","selection_count":1,"selections":[{"selection_name":"Each Team to Have 2+ Cards","odds":1.3636364,"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook","status":"Active"}]}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/price-boosts/batch":{"post":{"tags":["football"],"summary":"Batch price boosts for multiple events","description":"Fetch **price boost** offers for up to **50** event IDs in one request.  \n\nSame per-event JSON shape as `GET /v1/football/events/{event_id}/price-boosts`.  \n\nEvents with no snapshot or no price boosts after filters appear in `missing`.  \n\nRequires **Pro** or **Business**. Consumes **1** request per `event_id`.","operationId":"batch_event_price_boosts_v1_football_price_boosts_batch_post","security":[{"APIKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"examples":{"default":{"summary":"Batch price boosts for two events","value":{"event_ids":["evt_abc123","evt_def456"],"odds_format":"decimal"}}},"title":"Body"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Batch Event Price Boosts V1 Football Price Boosts Batch Post"},"examples":{"sample":{"summary":"Batch price boosts wrapper","value":{"schema_version":"1.0","sport":"football","requested":2,"returned":1,"missing":["evt_missing"],"odds":{"evt_06ce81ef6bf857d5f0b9eb54cc13":{"schema_version":"1.0","event_id":"evt_06ce81ef6bf857d5f0b9eb54cc13","captured_at":"2026-07-30T08:30:00Z","competition":"Brazilian Serie A","event_title":"Corinthians vs Atletico Paranaense","kickoff_utc":"2026-07-30T23:00:00Z","summary":{"markets_count":1,"bookmakers_count":2},"bookmakers":[{"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook"},{"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook"}],"markets":[{"market_id":3585748907,"market_name":"Price Boosts","market_group":"Price Boosts","selection_count":2,"selections":[{"selection_name":"Score from Outside the Box - Jesse Lingard","odds":9.5,"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook","status":"Active"},{"selection_name":"Kevin Viveros anytime goalscorer","odds":4.3333335,"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook","status":"Active"}]}]}}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/odds/batch":{"post":{"tags":["football"],"summary":"Batch odds for multiple events","description":"Fetch the latest odds for up to **50** event IDs in a single request.  \n\nMissing or unavailable events are omitted from the response (check `missing` in the reply).  \n\nAccepts the same `package`, `market`, `bookmakers`, `odds_format`, and `best_only` filters as the single-event endpoint.  \n\nConsumes usage quota proportional to batch size: core costs 1 request per event; full costs 2 requests per event.","operationId":"batch_event_odds_v1_football_odds_batch_post","security":[{"APIKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"examples":{"default":{"summary":"Batch two events","value":{"event_ids":["evt_abc123","evt_def456"],"package":"core","odds_format":"decimal"}}},"title":"Body"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Batch Event Odds V1 Football Odds Batch Post"},"examples":{"sample":{"summary":"Batch odds wrapper","value":{"schema_version":"1.0","sport":"football","requested":2,"returned":1,"missing":["evt_missing"],"odds":{"evt_06ce81ef6bf857d5f0b9eb54cc13":{"schema_version":"1.0","event_id":"evt_06ce81ef6bf857d5f0b9eb54cc13","captured_at":"2026-04-19T18:50:47.459641Z","competition":"Brazilian Serie B","event_title":"Novorizontino vs Athletic Club MG","kickoff_utc":"2026-04-19T23:00:00Z","summary":{"markets_count":1,"bookmakers_count":2},"bookmakers":[{"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook"},{"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook"}],"markets":[{"market_id":101,"market_name":"Win Market","market_group":"main","selection_count":6,"selections":[{"selection_name":"Novorizontino","odds":2.7,"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook","status":"Active"},{"selection_name":"Draw","odds":3.1,"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook","status":"Active"},{"selection_name":"Athletic Club MG","odds":2.55,"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook","status":"Active"}]}]}}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/specials":{"get":{"tags":["football"],"summary":"List football specials","description":"Paginated specials catalog. Requires a **Business / Scale** plan (same billing gate as the arbitrage API). Each successful call consumes **1** request against your quota.","operationId":"list_football_specials_v1_football_specials_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque pagination cursor from a previous response.","title":"Cursor"},"description":"Opaque pagination cursor from a previous response."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Football Specials V1 Football Specials Get"},"examples":{"sample":{"summary":"Specials catalog page","value":{"schema_version":"1.0","sport":"football","kind":"specials_catalog","count":1,"specials":[{"event_id":"evt_b2c4e6f890abcdef0123456789abcd12","path":"/football/specials/la-liga/next-real-madrid-manager","topic":"La Liga","slug":"next-real-madrid-manager","link_title":"Next Real Madrid manager","event_title":"Next Real Madrid manager","last_seen_at":"2026-04-30T12:00:00Z","latest_captured_at":"2026-04-29T18:30:10.123456Z","markets_with_odds":4,"unique_bookmaker_codes":9}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/football/specials/{event_id}/odds":{"get":{"tags":["football"],"summary":"Latest odds for one football special","description":"Latest multi-bookmaker odds for one football special. Use an `event_id` returned by `GET /v1/football/specials`. Requires a **Business / Scale** plan (same billing gate as the arbitrage API). Returns the full special snapshot. There is no `package` parameter. Each successful call consumes **1** request against your quota.","operationId":"get_football_special_odds_v1_football_specials__event_id__odds_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","title":"Event Id"}},{"name":"bookmaker_codes","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated bookmaker_code values (public UO* ids).","title":"Bookmaker Codes"},"description":"Comma-separated bookmaker_code values (public UO* ids)."},{"name":"odds_format","in":"query","required":false,"schema":{"enum":["decimal","fractional","american"],"type":"string","description":"decimal | fractional | american","default":"decimal","title":"Odds Format"},"description":"decimal | fractional | american"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Football Special Odds V1 Football Specials  Event Id  Odds Get"},"examples":{"sample":{"summary":"Special odds (sample)","value":{"schema_version":"1.0","event_id":"evt_b2c4e6f890abcdef0123456789abcd12","captured_at":"2026-04-29T18:30:10.123456Z","event_title":"Next Real Madrid manager","category":"specials","summary":{"markets_count":1,"bookmakers_count":2},"bookmakers":[{"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook"},{"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook"}],"markets":[{"market_id":99001,"market_name":"Next manager","market_group":"specials","selection_count":4,"selections":[{"selection_name":"Xabi Alonso","odds":2.5,"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook"},{"selection_name":"Raul","odds":5.0,"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook"}]}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/history/football/odds-timeline":{"get":{"tags":["history"],"summary":"Historical odds timeline (football)","description":"Timeline points for one event/market/selection slice. Consumes **1 request per capture** in the `from`/`to` window (minimum 1).","operationId":"football_odds_timeline_v1_history_football_odds_timeline_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"event_id","in":"query","required":true,"schema":{"type":"string","description":"Stable event id (evt_...).","title":"Event Id"},"description":"Stable event id (evt_...)."},{"name":"market_id","in":"query","required":true,"schema":{"type":"integer","description":"Numeric market id from odds payload.","title":"Market Id"},"description":"Numeric market id from odds payload."},{"name":"selection_name","in":"query","required":true,"schema":{"type":"string","description":"Selection name, e.g. Home / Draw / Away.","title":"Selection Name"},"description":"Selection name, e.g. Home / Draw / Away."},{"name":"bookmaker_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional bookmaker code filter (e.g. B3).","title":"Bookmaker Code"},"description":"Optional bookmaker code filter (e.g. B3)."},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Lower bound capture timestamp (inclusive, ISO-8601 UTC).","title":"From"},"description":"Lower bound capture timestamp (inclusive, ISO-8601 UTC)."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Upper bound capture timestamp (inclusive, ISO-8601 UTC).","title":"To"},"description":"Upper bound capture timestamp (inclusive, ISO-8601 UTC)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"description":"Max points to return (default 500).","default":500,"title":"Limit"},"description":"Max points to return (default 500)."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Football Odds Timeline V1 History Football Odds Timeline Get"},"examples":{"sample":{"summary":"Timeline points","value":{"schema_version":"1.0","sport":"football","filters":{"event_id":"evt_06ce81ef6bf857d5f0b9eb54cc13","market_id":101,"selection_name":"Novorizontino","bookmaker_code":"UO004","from":"2026-04-19T08:00:00Z","to":"2026-04-19T12:00:00Z","limit":500},"count":3,"points":[{"captured_at":"2026-04-19T08:00:00Z","odds":2.7,"quote_status":"OPEN"},{"captured_at":"2026-04-19T10:00:00Z","odds":2.65,"quote_status":"OPEN"},{"captured_at":"2026-04-19T12:00:00Z","odds":2.6,"quote_status":"OPEN"}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/history/football/events/{event_id}/captures":{"get":{"tags":["history"],"summary":"List historical snapshot capture times for a football event","description":"List available capture timestamps for a football event. Consumes **1** request.","operationId":"football_history_captures_v1_history_football_events__event_id__captures_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","title":"Event Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"description":"Maximum capture times to return.","default":1000,"title":"Limit"},"description":"Maximum capture times to return."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Football History Captures V1 History Football Events  Event Id  Captures Get"},"examples":{"sample":{"summary":"Capture times","value":{"schema_version":"1.0","sport":"football","event_id":"evt_06ce81ef6bf857d5f0b9eb54cc13","count":3,"captures":[{"captured_at":"2026-04-19T08:00:00Z"},{"captured_at":"2026-04-19T09:00:00Z"},{"captured_at":"2026-04-19T10:00:00Z"}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/history/football/events/{event_id}/snapshot":{"get":{"tags":["history"],"summary":"Get a historical odds snapshot for a football event","description":"Fetch a historical odds snapshot by capture time. Consumes quota like live odds: `package=core` = 1 request, `package=full` = 2 requests.","operationId":"football_history_snapshot_v1_history_football_events__event_id__snapshot_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","title":"Event Id"}},{"name":"captured_at","in":"query","required":true,"schema":{"type":"string","description":"Requested capture timestamp (ISO-8601 UTC).","title":"Captured At"},"description":"Requested capture timestamp (ISO-8601 UTC)."},{"name":"match","in":"query","required":false,"schema":{"enum":["exact","nearest","at_or_before","at_or_after"],"type":"string","description":"How to resolve the requested captured_at when no exact snapshot exists.","default":"at_or_before","title":"Match"},"description":"How to resolve the requested captured_at when no exact snapshot exists."},{"name":"package","in":"query","required":false,"schema":{"enum":["full","core"],"type":"string","description":"Historical odds package to return.","default":"core","title":"Package"},"description":"Historical odds package to return."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Football History Snapshot V1 History Football Events  Event Id  Snapshot Get"},"examples":{"sample":{"summary":"Historical snapshot","value":{"schema_version":"1.0","sport":"football","event_id":"evt_06ce81ef6bf857d5f0b9eb54cc13","requested_captured_at":"2026-04-19T09:30:00Z","resolved_captured_at":"2026-04-19T09:00:00Z","match":"at_or_before","package":"core","snapshot":{"schema_version":"1.0","event_id":"evt_06ce81ef6bf857d5f0b9eb54cc13","captured_at":"2026-04-19T18:50:47.459641Z","competition":"Brazilian Serie B","event_title":"Novorizontino vs Athletic Club MG","kickoff_utc":"2026-04-19T23:00:00Z","summary":{"markets_count":1,"bookmakers_count":2},"bookmakers":[{"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook"},{"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook"}],"markets":[{"market_id":101,"market_name":"Win Market","market_group":"main","selection_count":6,"selections":[{"selection_name":"Novorizontino","odds":2.7,"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook","status":"Active"},{"selection_name":"Draw","odds":3.1,"bookmaker_code":"UO004","bookmaker_name":"Bet365","bookmaker_type":"sportsbook","status":"Active"},{"selection_name":"Athletic Club MG","odds":2.55,"bookmaker_code":"UO019","bookmaker_name":"Paddy Power","bookmaker_type":"sportsbook","status":"Active"}]}]}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","description":"Your API key for `/v1/...` endpoints. Send it as `X-Api-Key: <value>`. Note: Swagger's **Authorize** button only stores the header value — it does not validate it until you execute a request.","in":"header","name":"X-Api-Key"}}},"tags":[{"name":"reference","description":"Catalog: sports, bookmakers, leagues, and documented market types."},{"name":"account","description":"Customer API key profile (`/v1/account/me`) for dashboards."},{"name":"football","description":"Football fixtures, football specials, latest pre-match odds snapshots, best odds, and 2-way arbitrage opportunities."},{"name":"history","description":"Historical odds timelines."}]}