Response Format

The API returns JSON. Response shapes are endpoint-specific; there is no single wrapper such as {data, metadata} for every route.

Dates and times use:

Field type	Format
Dates	`YYYY-MM-DD`
Game times	`HH:MM:SS`, Eastern Time
Timestamps	ISO 8601 string

Team names in authenticated model endpoints are usually normalized slugs such as new_york_yankees. The public website endpoint formats team names for display.

Prediction Response

GET /api/v1/predictions/{sport}/{model_type}

json

{
  "sport": "mlb",
  "model_type": "won_on_points",
  "predictions_date": "2026-05-23T14:12:05.000000",
  "games": [
    {
      "date": "2026-05-23",
      "time": "19:10:00",
      "away_team": "new_york_yankees",
      "home_team": "colorado_rockies",
      "predictions": {
        "IMPLIED": 0.3741,
        "BLEND": 0.4112,
        "XGB": 0.3929
      },
      "away_money_line": -135,
      "home_money_line": 115,
      "open_away_money_line": -128,
      "open_home_money_line": 108,
      "ev_away_ml": -3.1,
      "ev_home_ml": 1.8
    }
  ],
  "models_used": ["IMPLIED", "AI", "BLEND", "CATB", "RF", "LGB", "LOGR", "XGB", "XT"]
}

Common game fields:

Field	Meaning
`date`	Game date
`time`	Game time in Eastern Time. Important for doubleheaders.
`away_team`, `home_team`	Normalized team names
`predictions`	Model probabilities for the positive side

Probability axes:

Model type	Positive side	Negative side
`over_under`	Over	Under
`won_on_points`	Home moneyline	Away moneyline
`won_on_spread`	Home spread	Away spread

Line fields:

Model type	Fields
`over_under`	`over_under`, `over_line`, `under_line`, `open_over_under`
`won_on_points`	`away_money_line`, `home_money_line`, `open_away_money_line`, `open_home_money_line`
`won_on_spread`	`away_point_spread`, `home_point_spread`, `away_point_spread_line`, `home_point_spread_line`, `open_away_point_spread`, `open_home_point_spread`

Opening line fields can be null when no real opener is available. Placeholder zero openers are intentionally suppressed.

EV fields are informational calculations. They are not a validated betting selector.

Public ML Predictions Response

GET /api/v1/public/ml-picks/{sport}/{market}

json

{
  "sport": "mlb",
  "market": "moneyline",
  "model_type": "won_on_points",
  "predictions_date": "2026-05-23T14:12:05.000000",
  "games": [
    {
      "date": "2026-05-23",
      "time": "19:10:00",
      "away_team": "New York Yankees",
      "home_team": "Colorado Rockies",
      "pick": "Colorado Rockies ML",
      "pick_side": "home",
      "blend_probability": 0.4112,
      "confidence": 0.1776,
      "market_line": "ML -135/+115",
      "implied_probability": 0.3741,
      "lines": {
        "away_money_line": -135,
        "home_money_line": 115
      },
      "models": {
        "BLEND": 0.4112,
        "XGB": 0.3929
      }
    }
  ],
  "models_used": ["BLEND", "XGB", "RF", "LGB", "CATB", "LOGR", "XT"],
  "note": "Free ML predictions only. App workflows, MCP/CLI tools, and account features require a paid Scottfree Sports plan."
}

Odds Response

GET /api/v1/odds/{sport}

json

{
  "sport": "mlb",
  "date": "2026-05-23T16:00:00.000000",
  "games": [
    {
      "match_id": "abc123",
      "date": "2026-05-23",
      "time": "19:10:00",
      "away_team": "new_york_yankees",
      "home_team": "colorado_rockies",
      "away_money_line": -135,
      "home_money_line": 115,
      "over_under": 10.5,
      "over_line": -110,
      "under_line": -110,
      "last_updated": "2026-05-23 15:55:00"
    }
  ],
  "last_updated": "2026-05-23T16:00:00.000000"
}

Results Response

GET /api/v1/results/{sport}/{model_type}

Use the optional season query parameter for a stored historical season, for example ?season=2024&limit=5000 for MLB or ?season=2024-25&limit=5000 for a split-year sport. Valid labels are returned by GET /api/v1/results/{sport}/{model_type}/seasons.

Results include total, returned, offset, next_offset, snapshot, season, source_start, and source_end. Limits range from 1 to 100000 (default 100). Historical continuation requires an explicit season and the first page's snapshot. HTTP 409 means the artifact changed; restart rather than combine generations. Storage failures are errors, not empty history. Model-bearing history may cover less than the standalone historical product universe.

Recorded-v2 strategy responses identify accounting and price_basis; won is nullable and outcome distinguishes win/loss/push. Results preserve spread prices (home_point_spread_line, away_point_spread_line), total prices (over_line, under_line), quote provenance, and settlement evidence when available.

json

{
  "sport": "mlb",
  "model_type": "won_on_points",
  "results": [
    {
      "date": "2026-05-22",
      "time_est": "19:10:00",
      "away_team": "new_york_yankees",
      "home_team": "colorado_rockies",
      "away_score": 4.0,
      "home_score": 2.0,
      "won_on_points": 0.0,
      "BLEND": 0.4112,
      "IMPLIED": 0.3741,
      "open_home_money_line": 108.0,
      "home_money_line": 115.0
    }
  ],
  "last_updated": "2026-05-23T14:20:00.000000"
}

Result rows are flexible. Additional model, odds, target, and feature columns can appear as model artifacts evolve.

Historical rows reconstructed after the season identify that origin with model_probability_source="reconstructed_oos" and may include model_training_through and model_reconstruction_method. These are out-of-sample reconstructions, not contemporaneously archived predictions.

Summary Response

GET /api/v1/summary/{sport}/{model_type}

json

{
  "sport": "mlb",
  "model_type": "won_on_points",
  "summaries": [
    {
      "model": "BLEND",
      "total_games": 420,
      "wins": 214,
      "losses": 206,
      "win %": 50.95,
      "win % 4W": 51.8,
      "fade %": 49.05,
      "home %": 52.1,
      "away %": 47.9
    }
  ],
  "generated_date": "2026-05-23T14:20:00.000000"
}

The side labels are market-relative:

Model type	Summary side fields
`over_under`	`over %`, `under %`, `over % 1W`, `under % 1W`, `over % 4W`, `under % 4W`
`won_on_points`	`home %`, `away %`, `home % 1W`, `away % 1W`, `home % 4W`, `away % 4W`
`won_on_spread`	`home %`, `away %`, `home % 1W`, `away % 1W`, `home % 4W`, `away % 4W`

Sports Data Refresh Response

GET /api/v1/scottfree-sports-data/status

json

{
  "has_scottfree_sports_data": true,
  "expires_at": "2026-06-13T00:00:00+00:00",
  "owned_products": ["nfl_historical"],
  "owned_sports": ["nfl"],
  "refreshes_used": 1,
  "refreshes_remaining": 7,
  "refresh_limit": 8,
  "next_reset_at": "2026-06-01T00:00:00+00:00"
}

POST /api/v1/scottfree-sports-data/refresh

json

{
  "refreshes_remaining": 7,
  "next_reset_at": "2026-06-01T00:00:00+00:00",
  "downloads": [
    {
      "sport": "nfl",
      "filename": "nfl_game_scores_1g.csv",
      "url": "https://storage.googleapis.com/...",
      "expires_at": "2026-05-23T16:15:00+00:00"
    }
  ]
}

Error Response

The API error handler returns:

json

{
  "error": "HTTP_401",
  "detail": "Invalid or expired API key",
  "timestamp": "2026-05-23T16:00:00.000000"
}

Common statuses:

Status	Meaning
`400`	Bad request or invalid parameter
`401`	Missing, invalid, expired, or revoked API key
`403`	Valid key, insufficient plan permission
`404`	Data artifact not available
`429`	Rate limit or quota exceeded
`500`	Server error
`503`	Dependency unavailable

Response Format #

Prediction Response #

Public ML Predictions Response #

Odds Response #

Results Response #

Summary Response #

Sports Data Refresh Response #

Error Response #

Response Format

Prediction Response

Public ML Predictions Response

Odds Response

Results Response

Summary Response

Sports Data Refresh Response

Error Response