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.
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.
GET /api/client/fixtures HTTP/1.1 Host: api.oddscomposer.io Authorization: Bearer YOUR_API_TOKEN Accept: application/json
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.Base URL & environments
Production
https://api.oddscomposer.io/api/client
Sandbox
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
?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.
37.27.110.214
Timeout 15 s
Content full state, not a diff
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.
| Topic | How it works |
|---|---|
| Request | POST 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). |
| Security | Today 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 response | Any 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 size | Accept 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. |
| Retries | Today 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. |
| Ordering | Today 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. |
| Duplicates | Possible: 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 messages | Use 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 today | A 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.
event | player_lines | specials | Typical size |
|---|---|---|---|
fixture.created | Every line in your window | Yes | 0.1–1 MB |
fixture.updated | Every line in your window | Yes | 0.1–1 MB |
fixture.closed | Balanced lines, all suspended | Yes | under 50 KB |
fixture.inplay-updates | Live points ladder | Empty | up to ~175 KB |
fixture.inplay-settlement Opt-in | Only the lines settled now, with results | Settled specials, if any | a few KB |
fixture.inplay-closed Opt-in | Empty | Empty | under 2 KB |
fixture.settlement | Every line, with results | Yes, settled | up to ~8 MB |
heartbeat Opt-in | Not present | Not present | under 100 B |
// Node.js + Express const express = require('express'); const app = express(); app.use(express.json({ limit: '20mb' })); // settlement bodies can reach ~8 MB app.post('/webhooks/odds-composer', (req, res) => { if (req.get('X-API-KEY') !== process.env.OC_WEBHOOK_KEY) return res.sendStatus(401); const msg = req.body; if (msg.event === 'heartbeat') { console.log('heartbeat', msg.sent_at); } else { console.log(msg.event, msg.fixture_id, msg.sent_at, (msg.player_lines || []).length, 'lines,', (msg.specials || []).length, 'specials'); } res.sendStatus(200); // any 2xx within 15 s counts as delivered }); app.listen(8080);
# Python + Flask import os from flask import Flask, request app = Flask(__name__) app.config["MAX_CONTENT_LENGTH"] = 20 * 1024 * 1024 # settlement bodies can reach ~8 MB @app.post("/webhooks/odds-composer") def odds_composer(): if request.headers.get("X-API-KEY") != os.environ["OC_WEBHOOK_KEY"]: return "", 401 msg = request.get_json() if msg["event"] == "heartbeat": print("heartbeat", msg["sent_at"]) else: print(msg["event"], msg["fixture_id"], msg["sent_at"], len(msg.get("player_lines") or []), "lines,", len(msg.get("specials") or []), "specials") return "", 200 # any 2xx within 15 s counts as delivered
<?php // PHP, e.g. public/webhooks/odds-composer.php // Set post_max_size = 20M: settlement bodies can reach ~8 MB. if (($_SERVER['HTTP_X_API_KEY'] ?? '') !== getenv('OC_WEBHOOK_KEY')) { http_response_code(401); exit; } $msg = json_decode(file_get_contents('php://input'), true); if ($msg['event'] === 'heartbeat') { error_log('heartbeat ' . $msg['sent_at']); } else { error_log(sprintf('%s %d %s: %d lines, %d specials', $msg['event'], $msg['fixture_id'], $msg['sent_at'], count($msg['player_lines'] ?? []), count($msg['specials'] ?? []))); } http_response_code(200); // any 2xx within 15 s counts as delivered
// Go, standard library only package main import ( "encoding/json" "log" "net/http" "os" ) type Message struct { Event string `json:"event"` FixtureID int `json:"fixture_id"` SentAt string `json:"sent_at"` PlayerLines []json.RawMessage `json:"player_lines"` Specials []json.RawMessage `json:"specials"` } func main() { http.HandleFunc("/webhooks/odds-composer", func(w http.ResponseWriter, r *http.Request) { if r.Header.Get("X-API-KEY") != os.Getenv("OC_WEBHOOK_KEY") { w.WriteHeader(http.StatusUnauthorized) return } var msg Message body := http.MaxBytesReader(w, r.Body, 20<<20) // settlement bodies can reach ~8 MB if err := json.NewDecoder(body).Decode(&msg); err != nil { w.WriteHeader(http.StatusBadRequest) return } log.Println(msg.Event, msg.FixtureID, msg.SentAt, len(msg.PlayerLines), "lines,", len(msg.Specials), "specials") w.WriteHeader(http.StatusOK) // any 2xx within 15 s counts as delivered }) log.Fatal(http.ListenAndServe(":8080", nil)) }
// C# + ASP.NET Core minimal API (default body limit 30 MB) using System.Text.Json; var app = WebApplication.CreateBuilder(args).Build(); app.MapPost("/webhooks/odds-composer", async (HttpRequest req) => { if (req.Headers["X-API-KEY"] != Environment.GetEnvironmentVariable("OC_WEBHOOK_KEY")) return Results.Unauthorized(); using var doc = await JsonDocument.ParseAsync(req.Body); var msg = doc.RootElement; var ev = msg.GetProperty("event").GetString(); if (ev == "heartbeat") Console.WriteLine($"heartbeat {msg.GetProperty("sent_at")}"); else Console.WriteLine($"{ev} {msg.GetProperty("fixture_id")} {msg.GetProperty("sent_at")}: " + $"{msg.GetProperty("player_lines").GetArrayLength()} lines"); return Results.Ok(); // any 2xx within 15 s counts as delivered }); app.Run();
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.
| Field | Type | Meaning |
|---|---|---|
fixture_id | int | Fixture id, the same as id in /fixtures. |
event | string | fixture.created, fixture.updated, fixture.closed, fixture.inplay-updates, fixture.inplay-settlement, fixture.inplay-closed or fixture.settlement. |
sent_at | datetime | When this message was built, ISO 8601 UTC. Compare it to tell which message for a fixture is newest. |
inplay | bool | true when the fixture will also be offered in-play. |
start_time | datetime | Tip-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_at | datetime | Set once pre-match betting closed or results were saved, otherwise null. |
league_id · league_name | int · string | See /leagues. |
home_team_id · away_team_idhome_team_name · away_team_name | int · string | See /teams. |
home_players · away_players | object | Roster as { "player_id": "name" }. |
player_lines | array | Every line in your window: balanced lines and alternative lines (below). |
specials | array | Special markets for the fixture; see Specials. |
Fields of each line in player_lines
| Field | Type | Meaning |
|---|---|---|
id | int | Line id. Use it to upsert and to settle. |
player_id · player_name · player_team_id | int · string · int | The player and their team. |
market_type | string | See Market types. |
balance_line | float | The over/under line, always x.5. |
balance_line_over_odds · balance_line_under_odds | float | Decimal odds for over and under. |
milestone_line · milestone_over_odds | float | "X or more" market on the same line: milestone_line = balance_line + 0.5. |
is_balanced | bool | true for the main line of a player and market; false for alternative lines around it. |
is_suspended | bool | Do not offer while true. |
status | string | active or closed. |
balance_line_over_settlement · balance_line_under_settlement · milestone_over_settlement | string | Settlement messages only: W (won), L (lost) or V (void, e.g. the player did not play). Otherwise null. |
settlement_value | float | Settlement 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
| Field | Type | Meaning |
|---|---|---|
id | int | Selection id; use it to upsert and settle. |
fixture_id | int | The fixture. |
market_type | string | Market, see the table. |
selection_name | string | The selection: a threshold code or a player name. |
odds | float | Decimal odds. |
is_suspended | bool | Do not offer while true. Suspended selections can show 0 odds. |
status | string | active or closed. |
settlement | string | W, L, V, or null before settlement. |
Markets
| market_type | selection_name | Wins when |
|---|---|---|
any_home_team_player_to_reach_x_pointsany_away_team_player_to_reach_x_points | any_home_team_player_to_reach_20usually 15, 20, 25, 30 | At least one player of that team scores 20 or more points. |
any_home_team_player_to_reach_x_assistsany_away_team_player_to_reach_x_assists | any_away_team_player_to_reach_8usually 5, 8, 10, 12 | The same, for assists. |
any_home_team_player_to_reach_x_total_reboundsany_away_team_player_to_reach_x_total_rebounds | any_home_team_player_to_reach_10usually 8, 10, 12, 15 | The same, for rebounds. |
double_double | Player name | 10 or more in at least two of points, rebounds and assists. |
triple_double | Player name | 10 or more in all three of points, rebounds and assists. |
to-reach-triple-custom | Player name | 10 or more points, 5 or more rebounds and 5 or more assists. |
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.
| Value | Meaning | Value | Meaning |
|---|---|---|---|
points | Points | pa | Points + assists |
assists | Assists | pr | Points + rebounds |
total_rebounds | Rebounds | pra | Points + rebounds + assists |
blocks | Blocks | ra | Rebounds + assists |
steals | Steals | bs | Blocks + steals |
turnovers | Turnovers | three_point_field_goal | Three-pointers made |
Errors & status codes
| Status | When | Body |
|---|---|---|
| 200 OK | Request succeeded. An empty array means nothing matched your filters. | JSON |
| 400 Bad Request | fixture_id missing on /balanced-lines, /milestones or /fixture-player-lines. | {"error":"fixture_id is required","message":"Please provide at least fixture_id parameter"} |
| 403 Forbidden | Recovery & history endpoints: your account is not enabled for them yet. Contact Odds Composer. | {"error":"recovery_not_enabled", …} or {"error":"snapshot_not_enabled", …} |
| 404 Not Found | No 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 Conflict | POST /fixtures/{id}/resend: the fixture was deleted, so there is nothing to send. | {"error":"fixture_deleted", …} |
| 422 Unprocessable | Recovery & 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 Requests | More 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 Unavailable | Recovery & history endpoints: the history store is temporarily unreachable. Retry with backoff. | {"error":"recovery_unavailable", …} or history_unavailable |
| 5xx | Server-side problem. Retry with backoff and contact support if it persists. | Varies |
Typical workflow
- Call
/leaguesonce and cache the ids you care about. - Poll
/fixtures?league_id=…to discover upcoming games and theirids. Only fixtures with a non-nullpublished_atcarry published lines. - For each fixture pull
/balanced-lines?fixture_id=…for over/under props and/milestones?fixture_id=…for "X or more" props. - Resolve
player_idand team ids through/playersand/teams, or use theplayer_namealready present on line rows. - Watch
is_suspendedandstatuson every line. Suspended or closed lines must not be offered. Webhooks push these changes in real time. - 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/historyor 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 said | What 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 optional | fixture_id is required (400 otherwise). Only balanced rows are returned unless is_balanced=false. |
| Unauthorised returns 401 with a JSON error | Returns an empty 404. |
/fixtures/{id}/specials | Not available on the client API. Specials arrive inside the webhook messages and the snapshot; see Specials. |
Webhooks signed with an X-OddsComposer-Signature HMAC header | Not 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/webhooks | No 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. |