Getting Started

Base URL

All production API requests are made to:

https://api.odditt.com

Sandbox URL:

https://sandbox.odditt.com

All endpoints are prefixed with /v1/.

Prerequisites

Before you begin, make sure you have:

An API key provided by the Odditt team during onboarding.
An HTTP client - cURL, Postman, your application code, or any tool that can make HTTP requests.

That's it. No login step, no token exchange - just add your API key to a header and start making calls.

Your First API Call

Pass your API key in the X-API-Key header. Let's fetch the list of available sports:

curl https://api.odditt.com/v1/references/sports \
 -H "X-API-Key: YOUR_API_KEY"

You'll get back a paginated list of sports with their IDs and names. These IDs are what you'll use to drill deeper into the API.

Explore Your Data

The reference endpoints let you discover and map the entities in the Odditt system. Work from broad to specific: sports, then leagues, then teams and players.

List leagues for a sport

Pick a sport_id from the previous call and fetch its leagues:

curl "https://api.odditt.com/v1/references/leagues?sport_id=1&page=1&page_size=20" \
 -H "X-API-Key: YOUR_API_KEY"

List teams in a league

curl "https://api.odditt.com/v1/references/teams?league_id=7&page=1&page_size=20" \
 -H "X-API-Key: YOUR_API_KEY"

List players on a team

curl "https://api.odditt.com/v1/references/players?team_id=42&page=1&page_size=20" \
 -H "X-API-Key: YOUR_API_KEY"

All reference endpoints support search for partial name matching and are paginated. See Pagination for response format details.

📘
Tip
Most filter parameters accept either numeric IDs or External Keys (slug-style identifiers like nfl, nba). External keys are more human-readable, but numeric IDs are the stable contract — use those if you're building durable integrations.

Get Upcoming Events

Once you know which sport and league you're interested in, fetch upcoming events:

curl -X POST https://api.odditt.com/v1/events/upcoming-events \
 -H "X-API-Key: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "sport_id": 1,
    "league_id": 7,
    "page": 1,
    "page_size": 20
  }'

You can also filter by date range using event_start_date_from and event_start_date_to to narrow down to a specific window.

The response includes event IDs, team matchups, and scheduled start times. You'll use these event IDs in the next step.

Discover Trends: Flows and Mixed Flows

Odditt provides flows - curated statistical trends and insights about upcoming bets. See them in action at demo.odditt.com.

There are two main endpoints for retrieving flows:

Mixed Flows (recommended starting point)

Returns all flow types together (fact flows, fun flows, parlays) in a single paginated response:

curl -X POST https://api.odditt.com/v1/trends/mixed-flows \
 -H "X-API-Key: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "sport_id": 1,
    "league_id": 7,
    "page": 1,
    "page_size": 10
  }'

Both endpoints return the same underlying content - the difference is how it's delivered. Mixed flows gives you a pre-mixed feed where all flow types (fact flows, fun flows, parlays) are interleaved together in a single paginated list. This is the easiest way to get a diverse set of trends without managing each type separately.

Flows (unmixed, by type)

Returns the same content as mixed flows, but separated by type. You request one flow type at a time:

curl -X POST https://api.odditt.com/v1/trends/flows \
 -H "X-API-Key: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "sport_id": 1,
    "league_id": 7,
    "flow_type": "fact",
    "bet_type": "singles",
    "page": 1,
    "page_size": 10
  }'

Use this when you want to paginate through a single flow type (fact, fun, plain) or bet type (singles, parlay, same_game_parlay) independently - for example, if your UI has separate sections for each type or you need to apply statistical thresholds to a specific category.

When to use which

Endpoint	Delivery	Best for
Mixed Flows	Pre-mixed - all types interleaved in one list	General-purpose feeds, content displays, quick integration
Flows	Separated by type, each in its own list	Granular filtering, hit rate thresholds, type-specific pagination

Get Odds for an Event

For a specific event, retrieve the available betting markets and odds:

curl -X POST https://api.odditt.com/v1/odds/upcoming-odds-by-event \
 -H "X-API-Key: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "event_id": 12345,
    "page": 1,
    "page_size": 20
  }'

This returns the betting markets available for the event and the positions you can bet on within each market.

Mapping Bets: ETL Workflow

If you need to map Odditt's betting data to your own system, a typical ETL workflow looks like this:

Pull upcoming events for your target leagues using paginated calls to /v1/events/upcoming-events.
For each event, paginate through /v1/odds/upcoming-odds-by-event to get the full set of available bets.
Map bet identifiers using the dimension tables below so your system understands the betting market types and positions.

This approach gives you full coverage of all available bets for the events you care about.

Understanding Betting Dimensions

Three reference tables help you understand and categorize the bets returned by the API:

Betting Markets

Describes the types of bets available (e.g., moneyline, spread, totals, player props):

curl "https://api.odditt.com/v1/references/betting-markets?page=1&page_size=50" \
 -H "X-API-Key: YOUR_API_KEY"

Betting Market Positions

Describes the specific sides or positions within each market (e.g., over/under, home/away):

curl https://api.odditt.com/v1/references/betting-market-positions \
 -H "X-API-Key: YOUR_API_KEY"

Event Periods

Describes the time segments a bet can apply to (e.g., full game, first half, first quarter). See the API Reference for the full schema.

Together, these three dimensions let you fully classify any bet in the system.

Advanced Filtering

The API supports extensive filtering options across most endpoints - hit rate thresholds, implied probability ranges, operator filters, betting market filters, date ranges, and more. See the Filtering guide for the full reference.

Pagination

All list and search endpoints return paginated results. Use page and page_size parameters to navigate. See Pagination for the response format and best practices.

Advanced Authentication

For getting started, the X-API-Key header is all you need. For production deployments, you may want to use JWT tokens to reduce how often your API key is sent over the wire. The API supports both API key exchange and OAuth2 client credentials flows for obtaining tokens.

See the Advanced Authentication guide for details on token lifecycle, refresh flows, and best practices.

Next Steps

Browse the API Reference for complete endpoint documentation with request/response schemas.
Read Filtering to learn about all available query parameters.
Check Rate Limiting to understand your request limits.
See Response Format & Error Handling for HTTP status codes and error response formats.