Documentation

API Reference

Complete reference for every endpoint. Base URL: https://api.onxyodds.com/v1

All endpoints require the X-OXD-Key header. All responses return JSON with a data envelope and a meta block containing request_id and generated_at.

GET /matchups

Returns upcoming matchups for a sport and date window. Use predictions_available: true to filter to games the model has scored.

Request parameters

Parameter	Type	Required	Description
`sport`	string	Yes	Sport slug. Valid: `basketball`, `football`, `baseball`, `hockey`, `soccer`
`date`	string	No	ISO date (`YYYY-MM-DD`). Defaults to today in UTC.
`date_end`	string	No	End of date window. Max 7-day range.
`predictions_available`	boolean	No	If `true`, returns only matchups with scored predictions.

GET /v1/matchups?sport=basketball&date=2026-07-01&predictions_available=true
X-OXD-Key: oxd_live_sk_...

{
  "data": [
    {
      "matchup_id": "mup_9kx7m3a",
      "sport": "basketball",
      "scheduled_at": "2026-07-01T20:00:00Z",
      "home_team": {
        "id": "team_042",
        "label": "Home Club",
        "sport_league": "pro_bball"
      },
      "away_team": {
        "id": "team_071",
        "label": "Away Club",
        "sport_league": "pro_bball"
      },
      "venue": "Home Arena, Las Vegas NV",
      "predictions_available": true
    }
  ],
  "meta": { "request_id": "req_0kd2p9n4", "count": 1 }
}

GET /predictions

Returns win probabilities, upset-risk rating, and model confidence band for a specific matchup.

Request parameters

Parameter	Type	Required	Description
`matchup_id`	string	Yes	Matchup ID from `/matchups` response.

{
  "data": {
    "matchup_id": "mup_9kx7m3a",
    "home_win_prob": 0.61,
    "away_win_prob": 0.39,
    "upset_risk": "moderate",
    "confidence": {
      "band": "medium-high",
      "home_range": [0.54, 0.68],
      "away_range": [0.32, 0.46]
    },
    "key_factors": [
      { "label": "home_court_advantage", "weight": 0.14 },
      { "label": "recent_form_7_games", "weight": 0.22 }
    ],
    "model_version": "v4.1"
  }
}

upset_risk values

low - Favorite has probability > 0.74 with high confidence
moderate - Probability 0.55-0.74 or wide confidence band
high - Probability < 0.55 or the model recently mispredicted similar matchups

GET /talking-points

Returns 2-6 headline-ready talking points for a matchup. These are structured for direct CMS injection. Each object includes editorial tags for routing to specific templates or segments.

Request parameters

Parameter	Type	Required	Description
`matchup_id`	string	Yes	Matchup ID.
`type`	string	No	Filter by type: `upset_alert`, `confidence_band`, `form_trend`, `head_to_head`
`max`	integer	No	Maximum talking points returned. Range 1-6. Default 4.

{
  "data": [
    {
      "id": "tp_04ax1z",
      "type": "upset_alert",
      "headline": "Model flags moderate upset risk heading into tip-off",
      "body": "Away Club wins 39% of comparable matchups by model history...",
      "tags": ["upset_risk", "pre_game"],
      "confidence_note": "Medium-high model confidence on this matchup."
    },
    {
      "id": "tp_04ax2z",
      "type": "form_trend",
      "headline": "Home Club's recent seven-game stretch has been their strongest of the season",
      "body": "The model weights recent form at 22% for this matchup type, making the current run a material factor in the 61% projection.",
      "tags": ["form_trend", "pre_game"],
      "confidence_note": "High model confidence on recent form weighting."
    }
  ],
  "meta": { "matchup_id": "mup_9kx7m3a", "count": 2 }
}

GET /feed

Returns a chronological stream of pre-game prediction updates across sports. Use for building live alert feeds or real-time content panels. The feed is updated every 30 minutes as models refresh pre-game.

Request parameters

Parameter	Type	Required	Description
`sport`	string	No	Filter to one sport. Omit for all sports.
`since`	integer	No	Unix timestamp. Returns only items updated after this time.
`limit`	integer	No	Max results. Range 1-100. Default 25.
`update_type`	string	No	Filter by event type: `prediction_scored`, `prediction_revised`, `upset_flag_added`

{
  "data": [
    {
      "update_id": "upd_7p3k1q",
      "update_type": "prediction_scored",
      "matchup_id": "mup_9kx7m3a",
      "sport": "basketball",
      "updated_at": "2026-07-01T08:00:04Z",
      "summary": "Prediction first scored for mup_9kx7m3a. Home win prob: 0.61."
    }
  ],
  "meta": {
    "request_id": "req_0mn8r7t5",
    "count": 1,
    "next_since": 1751364004,
    // pass next_since in your next poll to get only new updates
    "poll_interval_seconds": 1800
  }
}

Use meta.next_since as the since parameter in your next request to implement efficient incremental polling. Honor meta.poll_interval_seconds to avoid unnecessary 429 responses.

Authentication headers

Every request must include the X-OXD-Key header with your full API key. Requests without a key return 401 Unauthorized. Keys are case-sensitive and must be sent as-issued.

X-OXD-Key: oxd_live_sk_<your-key>

Need an API key? Contact the team to request access.