# 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/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
- WebSocket message types: `welcome`, `created`, `updated`, `deleted`, `no_markets`, `resync_required`
- If replay cannot be served safely, the server sends `resync_required`
- Recovery path: fetch `/odds`, `/odds/multi`, or `/odds/all` 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 vary by sport:
- Football: `p1` (1st half), `fulltime` (90min)
- Ice Hockey: `p1`, `p2`, `p3`, `fulltime` (regulation), `overtime` (if applicable)
- Basketball: `p1`, `p2`, `p3`, `p4`, `fulltime`, `overtime`

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

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

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
GET /events/live?apiKey={key} - Get currently live events
GET /events/search?query={term}&apiKey={key} - Search events
GET /events/{id}?apiKey={key} - Get event by ID
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 /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