# Odds-API.io Documentation Index for AI Tools
# This file provides an index of documentation pages for LLMs and AI coding assistants

## Overview
Odds-API.io is a sports betting odds comparison API providing real-time data from 265 bookmakers across 34 sports.

## Documentation URLs

https://docs.odds-api.io/ - Introduction and overview of the API
https://docs.odds-api.io/quickstart - Get started with your first API call
https://docs.odds-api.io/authentication - API key authentication and security

## Guides

https://docs.odds-api.io/guides/fetching-odds - Fetch and compare odds from multiple bookmakers
https://docs.odds-api.io/guides/live-events - Live events, match clock and participant logos
https://docs.odds-api.io/guides/value-bets - Find positive expected value betting opportunities
https://docs.odds-api.io/guides/dropping-odds - Track significant odds movements from sharp bookmakers
https://docs.odds-api.io/guides/websockets - Real-time odds updates via WebSocket
https://docs.odds-api.io/guides/best-practices - Optimize API usage and performance

## API Reference

https://docs.odds-api.io/api-reference/introduction - API overview and authentication
https://docs.odds-api.io/api-reference/websocket - WebSocket API documentation

## AI Resources

https://docs.odds-api.io/llms-full.txt - Full documentation in a single file (for large context AI tools)
https://docs.odds-api.io/api-reference/openapi.json - OpenAPI specification with complete schemas

## WebSocket Reconnect

- Each WebSocket update includes a globally increasing `seq`
- Reconnect with `lastSeq` to receive a compacted replay of missed updates
- Replay is latest-state per `eventId:bookie`, not every intermediate tick
- Subscribe to channels with `?channels=odds,scores,status` (default `odds` keeps the existing stream); `scores`/`status` add `score`/`status` messages (event-level, best-effort, not replayed). `channels` is an allowlist — you get ONLY the channels you list, so include `odds` to keep receiving odds (`channels=scores,status` stops odds)
- `score` messages carry scores+periods only (no `status` field), sent on every score change; `status` messages are sent once per transition — `pending` (new match added), `live`, `settled`, `cancelled` — and include the current scores
- WebSocket message types: `welcome`, `created`, `updated`, `deleted`, `no_markets`, `score`, `status`, `resync_required`
- If replay cannot be served safely, the server sends `resync_required`
- Recovery path: fetch `/odds` or `/odds/multi` with `includeSeq=true`, read the `X-OddsAPI-Seq` header, then reconnect with `lastSeq`

## Base URL

https://api.odds-api.io/v3

## Scores & Period Scores

The API provides scores for all periods, not just the final result. The `scores` object contains `home`, `away`, and a `periods` map with the score for each period.

Period keys (top-level `home`/`away` is the OT/penalty-inclusive result):
- `p1`, `p2`, ... `pN` — period / set / quarter scores
- `ft` — full-time / regulation result
- `ot` — overtime / extra time / extra innings (when played)
- `ap` — penalty shootout tally (when decided on penalties)
- `currentgame` — current game points (live tennis)
- `map1`, `map2`, ... — per-map scores (esports)

So football uses `p1` + `ft`; ice hockey uses `p1`, `p2`, `p3`, `ft` (+ `ot`); basketball `p1`–`p4`, `ft` (+ `ot`). The full-time key is `ft` (the legacy feed used `fulltime`).

Example (football):
```json
"scores": { "home": 0, "away": 1, "periods": { "p1": { "home": 0, "away": 0 }, "ft": { "home": 0, "away": 1 } } }
```

Example (ice hockey decided in overtime):
```json
"scores": { "home": 4, "away": 3, "periods": { "p1": { "home": 0, "away": 1 }, "p2": { "home": 2, "away": 1 }, "p3": { "home": 1, "away": 1 }, "ft": { "home": 3, "away": 3 }, "ot": { "home": 4, "away": 3 } } }
```

Example (football decided on penalties):
```json
"scores": { "home": 1, "away": 1, "periods": { "p1": { "home": 0, "away": 1 }, "ft": { "home": 1, "away": 1 }, "ap": { "home": 4, "away": 3 } } }
```

This enables complete settlement of all market types including half-time results and period-specific markets.

## Key Endpoints

GET /sports - List available sports (no auth required)
GET /bookmakers - List available bookmakers (no auth required)
GET /leagues?sport={slug}&apiKey={key} - List leagues for a sport
GET /events?sport={slug}&apiKey={key} - List events for a sport. Defaults to the next 14 days when no `to` is given; pass `to` (RFC3339) to widen. Hard-capped at 5000/response — paginate with limit+skip.
GET /events/live?apiKey={key} - Get currently live events (includes optional clock object: minute, playedSeconds, period, running, statusDetail, serve, injuryTime)
GET /events/search?query={term}&apiKey={key} - Search events
GET /events/{id}?apiKey={key} - Get event by ID (live events include the clock object)
GET /odds?eventId={id}&bookmakers={list}&apiKey={key} - Get odds for an event
GET /odds/multi?eventIds={ids}&bookmakers={list}&apiKey={key} - Get odds for multiple events (up to 10)
GET /odds/updated?since={timestamp}&bookmaker={name}&sport={name}&apiKey={key} - Get recently updated odds
GET /odds/movements?eventId={id}&bookmaker={name}&market={name}&apiKey={key} - Get odds movement history
GET /value-bets?bookmaker={name}&apiKey={key} - Get value betting opportunities (optional: sport={slug}, league={slug} requires sport, includeEventDetails)
GET /arbitrage-bets?bookmakers={list}&apiKey={key} - Get arbitrage opportunities
GET /dropping-odds?sport={slug}&league={slug}&leagues={slug,slug}&markets={name,name}&apiKey={key} - Get dropping odds from sharp bookmakers (paid plans only). Use leagues (comma-separated) to filter by multiple leagues at once; mutually exclusive with league. Use markets (comma-separated) to filter by one or more market names.
GET /participants?sport={slug}&apiKey={key} - Get teams/participants
GET /participants/{id}/logo?apiKey={key} - Get participant crest as PNG (hotlinkable, cached 24h, 404 when none)
GET /bookmakers/selected?apiKey={key} - Get user's selected bookmakers
PUT /bookmakers/selected/select?bookmakers={list}&apiKey={key} - Select bookmakers

## Authentication

All endpoints except /sports and /bookmakers require an API key passed as query parameter:
?apiKey=YOUR_API_KEY

## Rate Limits

5,000 requests/hour on all plans
Additional packages: +10K/20K/30K requests/hour available

## Supported Sports (34 total)

football, basketball, tennis, baseball, american-football, ice-hockey, esports, darts, mixed-martial-arts, boxing, handball, volleyball, snooker, table-tennis, rugby, cricket, water-polo, futsal, beach-volleyball, aussie-rules, floorball, squash, beach-soccer, lacrosse, curling, padel, bandy, gaelic-football, beach-handball, athletics, badminton, cross-country, golf, cycling

## Contact

Support: hello@odds-api.io
Website: https://odds-api.io