Odds Composer Docs v3 Classic docs Console
REST API · Webhooks

Client API reference

Odds Composer publishes player prop lines and specials for basketball fixtures. Webhooks push every change to your endpoint as it happens; the read-only REST endpoints let you pull the same data with a Bearer token.

Base https://api.oddscomposer.io/api/client Auth Bearer token Format JSON Pull GET Push webhooks (HTTPS POST)

Authentication

Every endpoint sits behind token authentication. Send your API token in the Authorization header on each request. Tokens are issued per user from the Odds Composer console.

Request headers
GET /api/client/fixtures HTTP/1.1
Host: api.oddscomposer.io
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
Missing or invalid token returns an empty 404, not 401. The API deliberately hides the existence of client routes from unauthenticated callers. If you receive a 404 with no body on a path listed here, check the token first.
Keep the token server-side. Never ship it in browser or mobile code. Rotate it from the console if it leaks.

Base URL & environments

Production

URL
https://api.oddscomposer.io/api/client

Sandbox

URL
https://api.v2.test.oddscomposer.io/api/client

Both hostnames currently resolve to the same backend and dataset, so a token works on either. Integrate against the production hostname. All paths in this reference are relative to the base URL.

Conventions

FilteringQuery-string filters are exact-match on the named column, for example ?league_id=1. Unknown parameters are ignored. Response shapeList endpoints return a bare JSON array. There is no success wrapper and no pagination envelope. The recovery & history endpoints are the exception: they return a paginated object. BooleansBoolean columns come back as true/false. When filtering, pass 1/0 (or true/false for is_balanced). DatesMost timestamps are ISO 8601 in UTC. The fixtures endpoint additionally formats gamedate and published_at as DD.MM.YYYY HH:mm. Limits/fixtures without recovery parameters returns at most 20 rows, newest game date first. Narrow with league_id, team_id or gamedate, or use /fixtures?changed_since=… for a complete, paginated list. Other list endpoints are not capped. Rate limits/fixtures/history and the /recovery/… paths allow 60 requests per minute per token (429 beyond that). No other throttling is enforced at the moment. Treat this as subject to change and cache what you can.

Webhooks

Webhooks are the main way to receive Odds Composer data. Every time a fixture you receive changes, we send its full current state to your HTTPS endpoint as a JSON POST. You don't have to poll. The REST endpoints above carry the same data and serve as your backup and for spot checks.

Transport HTTPS POST · JSON Auth API key in a request header From IP 37.27.110.214 Timeout 15 s Content full state, not a diff
SetupSend us your endpoint URL. We register it on our side and give you the API key we will send with each request. There is no registration API or dashboard. One URLOne URL receives every event type. The heartbeat, if you take it, can go to a separate URL. EnvironmentsSandbox and production each get their own URL and API key. Both receive the same live fixture data. Your settingsLeagues, the alternative-line window per market and the date format are set per client. Every message you receive already has your settings applied.

Event pipeline

How you start receiving events, then the messages one fixture produces, from publishing to the final settlement. Click an event to see when it is sent, what it contains and an example request. Opt-in events are switched on per client.

Setup before your first event · once

→ → →
↓

Pre-match publish → tip-off

→ →
↓

In-play tip-off → final buzzer · opt-in

→ →
→

Settlement after the game · with or without in-play

Always on

Opt-in. Once switched on for you, it runs all the time: one ping per minute, game or no game, not tied to any fixture.

Delivery

How every request reaches you today. Today marks the current behaviour. On request marks options we set up for your pipeline when you ask.

TopicHow it works
RequestPOST to your URL with Content-Type: application/json, your API key in the header name agreed with you (for example X-API-KEY), and X-Request-Timestamp: the time of this delivery attempt (ISO 8601 UTC).
SecurityToday Static API key per environment, plus one fixed source IP you can allow-list: 37.27.110.214.
On request HMAC-SHA256 signature over the timestamp and the exact body, with a secret per environment.
Your responseAny 2xx counts as delivered. A non-2xx status or no reply within 15 s counts as a failed delivery, so answer before any long processing. The body of your response is ignored.
Body sizeAccept request bodies of at least 10 MB. Update messages are typically 0.1–1 MB, depending on your line window. Settlement messages for large games can reach about 8 MB.
RetriesToday Pre-match messages are not retried. Because every message carries the full fixture, the next message for that fixture brings you up to date, and recovery covers longer outages. In-play messages are retried automatically with backoff (1 s up to 30 s), always with the newest data.
On request A pre-match retry policy for your pipeline: which statuses, how long and how often.
OrderingToday Pre-match messages for one fixture can arrive out of order. The top-level sent_at shows which message is newest. In-play messages carry a per-fixture sequence number in X-Inplay-Seq.
On request A per-fixture sequence number and a message_id on pre-match messages too.
DuplicatesPossible: an update can repeat with the same content, and settlement is sent again when results are corrected. Every message is a full snapshot, so the same message twice carries the same state. Line ids identify the same line across messages.
Missed messagesUse recovery & history to list what we sent while you were down, then fetch the current state with /fixtures/{id}/snapshot or ask for a resend. These endpoints are switched on per client.
Not sent todayA change of start time or a deleted fixture does not produce a message. If a fixture disappears from your list or its time looks wrong, re-check it with /fixtures.

Receiving messages

Every message arrives as one HTTP POST with a JSON body, and the event field says what it is. How you store and use the data is up to your system. The table shows what each event carries; the examples only show how to accept a request in a few common stacks, read its fields and answer.

eventplayer_linesspecialsTypical size
fixture.createdEvery line in your windowYes0.1–1 MB
fixture.updatedEvery line in your windowYes0.1–1 MB
fixture.closedBalanced lines, all suspendedYesunder 50 KB
fixture.inplay-updatesLive points ladderEmptyup to ~175 KB
fixture.inplay-settlement Opt-inOnly the lines settled now, with resultsSettled specials, if anya few KB
fixture.inplay-closed Opt-inEmptyEmptyunder 2 KB
fixture.settlementEvery line, with resultsYes, settledup to ~8 MB
heartbeat Opt-inNot presentNot presentunder 100 B
Receiver examples

Every example checks the API key, logs the event and answers 200. The header name X-API-KEY is a placeholder for the one agreed with you.

Payload fields

Every fixture message has the same top-level shape, and it matches /fixtures/{id}/snapshot. The tables list the fields to build on. Messages can carry additional fields; ignore any you don't recognise.

FieldTypeMeaning
fixture_idintFixture id, the same as id in /fixtures.
eventstringfixture.created, fixture.updated, fixture.closed, fixture.inplay-updates, fixture.inplay-settlement, fixture.inplay-closed or fixture.settlement.
sent_atdatetimeWhen this message was built, ISO 8601 UTC. Compare it to tell which message for a fixture is newest.
inplaybooltrue when the fixture will also be offered in-play.
start_timedatetimeTip-off. Default format DD.MM.YYYY HH:mm in Europe/Tallinn time; ISO 8601 UTC is available per client and recommended for new integrations.
closed_at · settlement_atdatetimeSet once pre-match betting closed or results were saved, otherwise null.
league_id · league_nameint · stringSee /leagues.
home_team_id · away_team_id
home_team_name · away_team_name
int · stringSee /teams.
home_players · away_playersobjectRoster as { "player_id": "name" }.
player_linesarrayEvery line in your window: balanced lines and alternative lines (below).
specialsarraySpecial markets for the fixture; see Specials.

Fields of each line in player_lines

FieldTypeMeaning
idintLine id. Use it to upsert and to settle.
player_id · player_name · player_team_idint · string · intThe player and their team.
market_typestringSee Market types.
balance_linefloatThe over/under line, always x.5.
balance_line_over_odds · balance_line_under_oddsfloatDecimal odds for over and under.
milestone_line · milestone_over_oddsfloat"X or more" market on the same line: milestone_line = balance_line + 0.5.
is_balancedbooltrue for the main line of a player and market; false for alternative lines around it.
is_suspendedboolDo not offer while true.
statusstringactive or closed.
balance_line_over_settlement · balance_line_under_settlement · milestone_over_settlementstringSettlement messages only: W (won), L (lost) or V (void, e.g. the player did not play). Otherwise null.
settlement_valuefloatSettlement messages only: the player's final number for this market.

Specials

Specials are fixture-level markets beyond single-player lines: "any home player to reach 20 points", double-double and triple-double. They travel inside the fixture messages as the specials array: in fixture.created, fixture.updated and fixture.settlement, and in /fixtures/{id}/snapshot. There is no separate specials endpoint.

Fields

FieldTypeMeaning
idintSelection id; use it to upsert and settle.
fixture_idintThe fixture.
market_typestringMarket, see the table.
selection_namestringThe selection: a threshold code or a player name.
oddsfloatDecimal odds.
is_suspendedboolDo not offer while true. Suspended selections can show 0 odds.
statusstringactive or closed.
settlementstringW, L, V, or null before settlement.
specials in fixture.updated · click a field

      

Markets

market_typeselection_nameWins when
any_home_team_player_to_reach_x_points
any_away_team_player_to_reach_x_points
any_home_team_player_to_reach_20
usually 15, 20, 25, 30
At least one player of that team scores 20 or more points.
any_home_team_player_to_reach_x_assists
any_away_team_player_to_reach_x_assists
any_away_team_player_to_reach_8
usually 5, 8, 10, 12
The same, for assists.
any_home_team_player_to_reach_x_total_rebounds
any_away_team_player_to_reach_x_total_rebounds
any_home_team_player_to_reach_10
usually 8, 10, 12, 15
The same, for rebounds.
double_doublePlayer name10 or more in at least two of points, rebounds and assists.
triple_doublePlayer name10 or more in all three of points, rebounds and assists.
to-reach-triple-customPlayer name10 or more points, 5 or more rebounds and 5 or more assists.
Player specials are identified by name. selection_name holds the player's name exactly as in home_players / away_players of the same message, so you can map it to a player_id there. First scorer, top scorer, first assist and first rebound are disabled for the time being.

Market types

Values seen in the market_type field of lines. Compound markets are sums of the listed stats.

ValueMeaningValueMeaning
pointsPointspaPoints + assists
assistsAssistsprPoints + rebounds
total_reboundsReboundspraPoints + rebounds + assists
blocksBlocksraRebounds + assists
stealsStealsbsBlocks + steals
turnoversTurnoversthree_point_field_goalThree-pointers made

Errors & status codes

StatusWhenBody
200 OKRequest succeeded. An empty array means nothing matched your filters.JSON
400 Bad Requestfixture_id missing on /balanced-lines, /milestones or /fixture-player-lines.{"error":"fixture_id is required","message":"Please provide at least fixture_id parameter"}
403 ForbiddenRecovery & history endpoints: your account is not enabled for them yet. Contact Odds Composer.{"error":"recovery_not_enabled", …} or {"error":"snapshot_not_enabled", …}
404 Not FoundNo or invalid Bearer token, or an unknown path. On /fixtures/{id}/snapshot and /fixtures/{id}/resend: the fixture does not exist, is not published or is not in your leagues.Empty, or {"error":"fixture_not_found", …}
409 ConflictPOST /fixtures/{id}/resend: the fixture was deleted, so there is nothing to send.{"error":"fixture_deleted", …}
422 UnprocessableRecovery & history endpoints: invalid parameter, a window whose end is not after its start, a size above the maximum, a malformed cursor, or a resend event that does not fit the fixture's state (event_not_allowed).{"error":"invalid_window", …}, invalid_cursor, or Laravel validation errors
429 Too Many RequestsMore than 60 requests per minute on /fixtures/history, /fixtures/{id}/resend or /recovery/…, or a second resend of the same fixture within 30 s (resend_too_soon). Honour Retry-After.Laravel default
503 Service UnavailableRecovery & history endpoints: the history store is temporarily unreachable. Retry with backoff.{"error":"recovery_unavailable", …} or history_unavailable
5xxServer-side problem. Retry with backoff and contact support if it persists.Varies

Typical workflow

  1. Call /leagues once and cache the ids you care about.
  2. Poll /fixtures?league_id=… to discover upcoming games and their ids. Only fixtures with a non-null published_at carry published lines.
  3. For each fixture pull /balanced-lines?fixture_id=… for over/under props and /milestones?fixture_id=… for "X or more" props.
  4. Resolve player_id and team ids through /players and /teams, or use the player_name already present on line rows.
  5. Watch is_suspended and status on every line. Suspended or closed lines must not be offered. Webhooks push these changes in real time.
  6. If your webhook receiver was down, use recovery & history: list what was sent with /fixtures?changed_since=…, then re-check the missed messages with /fixtures/history or fetch the current state with /fixtures/{id}/snapshot.

Changes from the classic docs

This page was rebuilt from the live route definitions. Where the classic page and the running API disagreed, this page follows the API.

Classic page saidWhat the API actually does
Responses wrapped in {success, data, pagination}Bare JSON array, no pagination. /fixtures is capped at 20 rows.
/fixtures?date=…&status=…No date or status filter. Use gamedate, league_id, team_id and the other columns listed on the endpoint.
/balanced-lines filters optionalfixture_id is required (400 otherwise). Only balanced rows are returned unless is_balanced=false.
Unauthorised returns 401 with a JSON errorReturns an empty 404.
/fixtures/{id}/specialsNot available on the client API. Specials arrive inside the webhook messages and the snapshot; see Specials.
Webhooks signed with an X-OddsComposer-Signature HMAC headerNot sent today. Requests carry your API key header and come from one fixed IP. HMAC signing is available on request; see Delivery.
Register endpoints with POST /v1/webhooksNo registration API. Send us your URL and we set it up; see Webhooks.
Not documented/apitest, /teams, /players, /milestones and /fixture-player-lines are now covered.
© Odds Composer Reference generated from the live API on 2026-09-14 · recovery & history added 2026-10-01 · resend 2026-10-01 · webhooks & specials 2026-11-03 Classic docs