{
  "schema_version":       "1.0.0",     // optional; alias schemaVersion
  "checkpoint":           "pre_draft", // optional
  "roster_slots":        [{ "position": "OF", "count": 3 }, /* ... */],
  "scoring_categories":  [{ "name": "HR", "type": "batting" }, /* ... */],
  "total_budget":        260,         // per-team auction budget
  "num_teams":           12,          // optional, default 12
  "league_scope":        "Mixed",     // "Mixed" | "AL" | "NL"
  "scoring_format":      "5x5",       // optional: 5x5 | 6x6 | points
  "drafted_players": [{
    "player_id":  "695243",    // String(mlbId) — canonical key
    "name":       "Player Name",
    "position":   "OF",        // or use positions[] / roster_slot
    "team":       "NYY",
    "team_id":    "team_1",
    "paid":       42,          // optional auction price
    "is_keeper":   false,       // optional
    "pick_number": 3            // optional
  }],
  "deterministic":      false,       // optional — stable timestamps for tests
  "seed":                 42,            // optional — with deterministic, stable tie-breaks
  "player_ids":          ["660271"],   // optional — limit valuations[]; inflation uses full pool
  "user_team_id":        "team_1",       // optional — defaults to team_1 for team_adjusted_value
  "budget_by_team_id":  { "team_1": 200 }, // optional — per-team $ remaining
  "minors":              [],              // optional — [{ team_id, players[] }]
  "taxi":                []               // optional
}

{
  "engine_contract_version": "1",  // API contract id — detect drift vs Draft
  "valuation_model_version": "amethyst-api@1.0.0",  // or git SHA in production image
  "inflation_factor":      1.12,    // >1.0 = inflated market
  "inflation_model":       "replacement_slots_v2",
  "total_budget_remaining": 2184,
  "pool_value_remaining":   1948,
  "players_remaining":      496,
  "recommended_bid_note": "recommended_bid is a phase-aware model clearing target (star floors, pitcher dampening, isotonic smoothing)—a bidding guide, not a prediction of the winning hammer price; room behavior can diverge materially.",
  "team_adjusted_value_note": "team_adjusted_value scales adjusted_value by roster need, dollars per open slot vs league peers, remaining-slot scarcity, and replacement drop-off for eligible slots; when the league snapshot is symmetric (no auction picks, no keeper/minors/taxi off-board ids, equal per-team budgets in budget_by_team_id when provided, equal rostered counts per team), it equals adjusted_value",
  "phase_indicator": "early",
  "user_team_id_used": "team_1",
  "valuations": [{
    "player_id":      "660271",
    "name":           "Shohei Ohtani",
    "position":       "DH",
    "tier":           1,
    "baseline_value": 58,
    "adjusted_value": 65,        // market marginal value
    "recommended_bid": 72.5,      // phase-aware clearing estimate
    "team_adjusted_value": 78.2, // need + $/slot vs league + replacement drop-off
    "edge": 5.7,               // team_adjusted_value − recommended_bid
    "indicator":      "Steal",    // "Steal" | "Reach" | "Fair Value"
    "baseline_components": {
      "scoring_format": "5x5",
      "projection_component": 4.2,
      "scarcity_component": 0.1
    },
    "scarcity_adjustment": 0,       // embedded in baseline_value
    "inflation_adjustment": 7        // adjusted − baseline
  }],
  "calculated_at": "2026-03-07T17:39:19Z"
}

If post-calculation sanity checks fail, the API returns 422 with the same { errors: [...] } shape as Zod validation — no valuations payload. This route is not Redis-cached (fresh prices after catalog sync). Request body limit 1 MB. Per-key rate limits are configurable (RATE_LIMIT_* env vars; see OpenAPI / README).

{
  "player_id": "660271",
  "schema_version": "1.0.0",
  "roster_slots": [{ "position": "OF", "count": 3 }],
  "scoring_categories": [{ "name": "HR", "type": "batting" }],
  "total_budget": 260,
  "num_teams": 12,
  "user_team_id": "team_1",
  "drafted_players": []
}

{
  "engine_contract_version": "1",
  "inflation_factor": 1.12,
  "players_remaining": 496,
  "valuations": [{ /* single row */ }],
  "player": {
    "player_id": "660271",
    "name": "Shohei Ohtani",
    "baseline_value": 58,
    "adjusted_value": 65,
    "recommended_bid": 72.5,
    "team_adjusted_value": 78.2,
    "edge": 5.7,
    "indicator": "Steal"
  }
}

{
  "player_ids":     ["660271", "592450"],
  "league_scope":   "Mixed"
}

{
  "engine_contract_version": "1",
  "players": [{
    "player_id": "660271",
    "name":      "Shohei Ohtani",
    "position":  "DH",
    "team":      "LAD",
    "value":     58,
    "tier":      1,
    "adp":       1
  }]
}

{
  "drafted_players":     [ /* same DraftedPlayer shape as above */ ],
  "scoring_categories":  [{ "name": "SV", "type": "pitching" }],
  "position":           "SS",    // optional — filter to one position
  "num_teams":          12,
  "league_scope":       "Mixed"
}

{
  "positions": [{
    "position":          "SS",
    "elite_remaining":   2,     // tier-1 still available
    "mid_tier_remaining":5,
    "total_remaining":   18,
    "scarcity_score":    74,    // 0–100, higher = more scarce
    "alert":             "Only 2 elite SS remain"
  }],
  "monopoly_warnings": [{
    "team_id":           "team_3",
    "category":          "SV",
    "share_percentage":  62,
    "message":           "team_3 controls 62% of SV"
  }]
}

{
  "pick_order":   ["team_1", "team_2"],   // team_ids in draft order
  "roster_slots": [{ "position": "SP", "count": 5 }],
  "league_scope": "Mixed",
  "teams": [{
    "team_id":         "team_1",
    "budget_remaining": 180,       // optional
    "roster":          [ /* DraftedPlayer[] already on this team */ ]
  }],
  "available_player_ids": ["695243", /* ... */]  // optional explicit pool
}

{
  "predictions": [{
    "team_id":     "team_1",
    "pick_position": 1,
    "confidence":  0.82,              // 0–1
    "predicted_player": {
      "player_id": "660271",
      "name":      "Shohei Ohtani",
      "position": "DH",
      "adp":       1,
      "reason":    "Team needs DH (urgency 90%); best available by ADP."
    }
  }]
}

# days     — lookback window (default: 7)
# signal_type — filter: injury | role_change | trade | demotion | promotion

GET /signals/news?days=3&signal_type=injury

{
  "signals": [{
    "player_id":     "695243",     // present when matched to DB player
    "player_name":   "Player Name",
    "signal_type":   "injury",
    "severity":      "high",       // "low" | "medium" | "high"
    "description":   "Placed on 10-day IL",
    "effective_date":"2026-03-07",
    "source":        "MLB Transactions API"
  }],
  "count": 4
}