API Reference

ScrimmageLab API

REST endpoints powering ScrimmageLab's rankings, projections, draft tools, articles, and AI analysis. Use the catalog below to browse by category, or jump straight into the interactive Swagger UI to send live requests.

v1.0.0 · 181 documented endpoints

Quick start

curl https://scrimmagelab.com/api/draft-guide/rounds?teams=12&scoring=PPR

Authentication and Lab Pass requirements are described in each endpoint summary. This catalog does not currently infer those requirements reliably from OpenAPI metadata. See pricing for access options.

Draft Guide

Composite expert rankings, ADP arbitrage, sleepers, busts, tier breaks, scarcity curves, and round-by-round draft prep.

  • GET/api/draft-guide/arbitrageTry it →

    ADP vs consensus arbitrage — steals (going late) or fades (going early)

    Computes the gap between consensus expert ranking and live ADP. Players going LATER than their consensus rank are steals; players going EARLIER are fades. Sorted by absolute gap so the biggest mispricings surface first.

  • GET/api/draft-guide/badgesTry it →

    ml risk badges for a single player

    return the (up to 5) ml risk/upside badges for ``player_id``.

  • POST/api/draft-guide/badgesTry it →

    ml risk badges for many players (batch)

    return ``{player_id_str: [badges]}`` for every requested player.

  • GET/api/draft-guide/bustsTry it →

    top-30-ADP players with evidence-backed caution signals

    Returns top-30-ADP players with an affirmative caution signal: high week-to-week coefficient of variation or assignment to a replacement-level performance cluster. Absence from a breakout list is not negative evidence, and this endpoint does not estimate a calibrated bust probability.

  • GET/api/draft-guide/compositeTry it →

    composite house ranking with per-source breakdown

    Returns the house composite ranking — a weighted blend of every registered expert source — alongside a per-source breakdown so callers can see which experts contributed to each player's rank. Supports scoring (ppr/half/std), format (redraft/dynasty), position filter, and a limit cap.

  • GET/api/draft-guide/handcuffsTry it →

    for an RB, find the next-best running back on the same team

    Given a starting RB, returns the next-best running back on the same NFL team — the canonical handcuff pick. Includes composite rank and ADP for the handcuff so you can decide whether the insurance is worth the cost.

  • GET/api/draft-guide/idp/compositeTry it →

    IDP FantasyPros ECR board — defensive players, separate from offense

    Returns the IDP (Individual Defensive Player) board for DL, LB, and DB. Current inputs are FantasyPros ECR page feeds from one provider, not an independent multi-provider consensus. It remains separate from the offensive composite because IDP scoring varies by league.

  • GET/api/draft-guide/idp/sourcesTry it →

    IDP-only expert ranking sources (slug LIKE 'fantasypros_ecr_idp_%')

    Lists the subset of expert ranking sources that publish IDP rankings (currently FantasyPros ECR IDP feeds). Mirrors /sources but scoped to the defensive composite.

  • GET/api/draft-guide/moversTry it →

    paired-source rank movement for the verified current fantasy pool

    Tracks how much each verified current-pool player's expert rank moved over the last N days. Only sources present at both endpoints are paired, with at least two paired sources required, so source-list churn cannot masquerade as player movement.

  • GET/api/draft-guide/roundsTry it →

    round-by-round draft guide with value tags and decision drivers

    build the full round-by-round payload for a draft guide ui. response shape: { "rounds": [ { "round": 1, "picks_in_round": <teams>, "picks": [{pick_in_round, overall_pick, player_id, name, position, team_abbr, headshot_url, overall_rank, adp_rank, adp_delta, tier, value_tag, drivers[], news[]}, ...] }, ... ], "meta": {teams, max_round, adp_is_fallback, include_news} }

  • GET/api/draft-guide/scarcityTry it →

    position scarcity curves — overall rank of the Nth-best at each position

    Returns scarcity curves showing the overall draft rank of the Nth-best player at each position. Steeper curves indicate that waiting is risky; flat curves mean depth at the position is plentiful.

  • GET/api/draft-guide/scarcity-heatmapTry it →

    per-round x per-position scarcity grid + starter-tier ETA callouts

    build a 4 (positions) x N (rounds) grid showing how many players at each position have been drafted and how many starter-tier players remain by round, using the composite ranking (ADP-blended) as the draft order. grid + ETAs feed the position scarcity heatmap UI so drafters can see when each position's starter pool runs out (e.g. "RB1 tier exhausted by pick 11" — wait too long and you're left with replacement-level RBs).

  • GET/api/draft-guide/sleepersTry it →

    players the house ranks meaningfully better than their live ADP

    Surfaces sleeper candidates: players inside the house top 150 whose live ADP is meaningfully later than their composite rank (gap >= max(12 spots, 20% of composite rank)). These are the value picks the draft market is letting slide. Returns an honest empty list with a reason when no ADP data exists for the requested scoring/format.

  • GET/api/draft-guide/sourcesTry it →

    registered expert ranking sources with freshness and weight metadata

    Lists every registered expert ranking source feeding the composite, with last-refresh timestamp and the weight used in the blend. Use this to audit which experts are stale or to debug a surprising composite rank.

  • GET/api/draft-guide/tier-breaksTry it →

    position-filtered draft bands and exact next-band starts

    Summarize the active draft bands filtered into position columns. response shape (per the contract): { "scoring": "PPR", "format": "redraft", "tiers": [ {"position":"RB", "tier_num":1, "tier_label":"SMASH_START", "count":6, "first_overall":1, "last_overall":6, "first_position_rank":1, "last_position_rank":6, "next_tier_starts_at":7, "players":["Bijan","Gibbs",...]}, ... ] } notes: * A current ADMIN-approved Home Team publication is preferred. Its reviewed overall bands are filtered by position without renumbering. * With no valid publication, the existing composite positional tiers remain the unchanged fallback. * first_overall, last_overall, and next_tier_starts_at are actual overall ranks; clients must not infer a boundary with last + 1.

  • GET/api/draft-guide/tiersTry it →

    composite ranking grouped by tier

    Same composite ranking as /composite, but bucketed into draft tiers — useful when you want to know which players are interchangeable at a given draft slot vs which represent a real drop-off.

  • GET/api/draft/adpTry it →

    aggregated ADP across platforms (pro)

    average draft position aggregated across ingested platforms (expert_rankings rows from adp-type sources, latest pull per source).

  • GET/api/draft/rankingsTry it →

    draft rankings (pro, preseason)

    preseason draft rankings from the forgestat composite (same source as /api/draft-guide/composite). pro tier required.

Players

Player profiles, weekly stats, season splits, comparisons, and search across the active NFL roster.

  • GET/api/players/{player_id}Try it →

    basic player info (public)

    return basic player profile. available on free tier.

  • GET/api/players/{player_id}/consensusTry it →

    multi-source consensus comparison + house rank rationale

    Return eligible external rankings, market/trade ranks, our house rank/tier/value-tag, decision drivers, and a one-paragraph rationale. Eligibility is derived from active overall registry rows typed ``expert`` or ``consensus``. Legacy source keys remain in the response for backward compatibility; house-derived synthesis rows are disclosed and excluded. public endpoint — no auth required (the existing GET /{id} is also public). Sources that are unavailable or ineligible return ``null`` for that key. Consensus stats (median/min/max) never include them.

  • GET/api/players/{player_id}/distributionTry it →

    full per-player point distribution (P10/P50/P90 + skewness + format advice)

    return the full distribution of weekly fantasy points for one player. diamond #3 of the Bible: ship distributions, not point estimates. mainstream sites publish "Mike Clay says 13.4 PPG"; we publish P10/P25/P50/P75/P90, skewness, boom/bust rates, consistency tier, and four format-specific advice cards (best ball, season-long must-win, DFS cash, DFS GPP). public endpoint — no auth required. weekly_scores are pulled from ``player_game_stats``; if the requested season has <8 games of data we fall back to the prior season and flag it in ``data_quality.fallback_note``. NEVER fabricates data — players with no stored historical sample return a ``data_quality.status == "no_data"`` payload.

  • GET/api/players/{player_id}/newsTry it →

    external news headlines for a player (link-out only)

    return recent external news for a player (espn + rotowire feeds). public endpoint. items link out to the source — we never republish full article body. snippets are short (<=240 chars) previews from the source-provided summary. empty list when no recent news matches the player.

  • GET/api/players/{player_id}/statsTry it →

    full stat history with filters (pro)

    full stat history with optional filters. pro tier required (demo mode bypasses).

  • GET/api/players/browseTry it →

    bounded active-player catalog browse

    Browse the verified current pool or explicitly browse the archive.

  • GET/api/players/by-sleeper-id/{sleeper_id}Try it →

    map a Sleeper player_id to our player record

    resolve a Sleeper player_id (e.g. ``"6794"``) to our internal player. used by the Start/Sit recommender to pre-fill rosters from a Sleeper league. returns ``null`` if no mapping exists. public endpoint.

  • GET/api/players/compareDeprecatedTry it →

    legacy player comparison endpoint; use /api/tools/player-compare

  • GET/api/players/searchTry it →

    fuzzy player search

    Fuzzy player search, current-fantasy scoped by default. Public endpoint — no auth required. ``scope=all`` is an explicit archive search and does not make those identities eligible for current tools.

  • GET/api/players/topTry it →

    top players by fantasy points

    return top players ranked by current-season fantasy points. public endpoint — no auth required.

Teams

Team dashboards, salary cap, schedule, live scores, standings, and matchup breakdowns.

  • GET/api/matchupsTry it →

    weekly matchups via query params (public)

    weekly matchups using query parameters. public endpoint.

  • GET/api/matchups/{game_id}Try it →

    detailed matchup analysis (pro)

    deep-dive matchup analysis for a single game. pro tier required.

  • GET/api/matchups/weekly/{week}Try it →

    all matchup previews for a week (pro)

    all matchup previews for a given week. pro tier required.

  • GET/api/odds/weekly/{week}Try it →

    betting lines for all games (pro)

    spreads, totals, and moneylines for all games in a given week.

  • GET/api/salary-cap/{team_abbr}Try it →

    team salary cap breakdown (public, detailed data for pro)

    salary cap breakdown by player. public endpoint; pro users get enhanced contract details later.

  • GET/api/scheduleTry it →

    current season schedule (public)

    current season schedule from nfl_games (nflverse ingest). public endpoint.

  • GET/api/scores/liveTry it →

    live game scores (public)

    live game scores during game windows, from espn's public scoreboard. returns only in-progress games — empty outside game windows (and all offseason), which is the correct answer, not a stub.

  • GET/api/teams/{team_abbr}/dashboardTry it →

    full sourced team overview (public)

    full team overview — roster, verified season context, schedule profile, articles, and fantasy assets. Authentication is optional.

  • GET/api/teams/{team_abbr}/rosterTry it →

    team roster grouped by position

    all players on the team, grouped by position group.

  • GET/api/teams/{team_abbr}/scheduleTry it →

    team season schedule

    full season schedule for a team. when ``season`` isn't supplied and the resolved season has no games yet, automatically falls back to the prior stored season and surfaces ``schedule_status: 'released_not_ingested_using_prior'`` so callers can distinguish local ingestion lag from league release status. the games array is returned under both ``schedule`` and ``games`` keys for back-compat with older list-shape consumers.

  • GET/api/teams/{team_abbr}/schedule-widgetsTry it →

    HomeTeam-style schedule widgets (grid, traps, sparkline)

    schedule-grid + trap-week + opponent-strength sparkline payload. falls back to the prior season silently if the requested season has no games stored yet, mirroring the /schedule endpoint's behaviour. callers can check `actual_season` to know which season was actually rendered.

  • GET/api/teams/standingsTry it →

    all 32 team standings (public)

    compute W-L records from nfl_games for every team in a single query. offseason: when the current season has no finished games yet and no explicit season was requested, fall back to last season's final standings instead of rendering an all-zero table.

Articles & News

AI-generated analysis articles, automated NFL news pipeline, newsletter signups, and tag-based discovery.

  • GET/api/articlesTry it →

    public article archive with search/filter

    searchable article archive with pagination. `q` is the canonical search parameter; `search` is kept as an alias for backwards-compat with existing /articles consumers. Both filter on title/excerpt/body via ILIKE (a tsvector index can drop in later without changing this contract).

  • GET/api/articles/{article_id}Try it →

    full article

    Return the full published article body; editorial articles are public.

  • POST/api/articles/{article_id}/assign-imageTry it →

    match and assign an image_library image to an article (admin)

    run the 5-tier matching algorithm for a single article and persist the result to articles.featured_image.

  • POST/api/articles/{article_id}/auto-tagTry it →

    derive content-grounded tags and merge with existing (admin)

    run the article auto-tagger for a single article. NEVER overwrites manually-set tags — only adds tags derived from article content. Returns the before/added/after sets so callers can see exactly what changed.

  • GET/api/articles/{article_id}/export.csvTry it →

    export article dataset as csv (pro)

    export player_game_stats for the most recent season, filtered by the article's primary tag/position. requires lab pass (pro tier).

  • GET/api/articles/{article_id}/related-entitiesTry it →

    players and teams mentioned in an article

    return player cards and team badges for entities linked in the article body.

  • POST/api/articles/assign-images/allTry it →

    batch-assign images from image_library to all articles (admin)

    run the matching algorithm for all published articles. ensures no two articles get the same image.

  • POST/api/articles/auto-tag-allTry it →

    bulk auto-tag every article missing tags or with empty tags (admin)

    run the auto-tagger across every article. by default only fills in articles whose tags are null/empty so we don't churn manually-curated tag sets. Set only_missing=false to merge derived tags into ALL articles.

  • GET/api/articles/by-player/{player_id}Try it →

    articles about a specific player

    return published articles linked to a player via article_players junction.

  • GET/api/articles/by-team/{abbr}Try it →

    articles about a specific team

    return published articles linked to a team via article_teams junction or tags array.

  • GET/api/articles/latestTry it →

    last N articles (public)

    Return the public article feed; list cards use excerpts.

  • GET/api/articles/tags/popularTry it →

    most-used tags across published articles

    return the top tags (by frequency) for the filter chip row.

  • POST/api/news/draft-ingestTry it →

    ingest nfl draft picks and generate articles

    ingest nfl draft picks from sleeper and generate articles. pulls the latest player data from sleeper, detects new draft picks, creates player records if needed, and generates per-round articles with historical draft analysis context.

  • GET/api/news/latestTry it →

    latest news articles from the pipeline

    return the most recent news articles generated by the pipeline. pipeline-generated articles have model_used='news_pipeline_v1'. optionally filter by article type.

  • POST/api/news/run-pipelineTry it →

    manually trigger the news pipeline (admin)

    Manually run the database-writing news pipeline. Requires admin. this is the same as the celery task but triggered on-demand.

  • GET/api/news/trendingTry it →

    trending players with analysis context

    return sleeper trending add/drop players enriched with our statistical context. each player includes: avg ppg, trade value, trend slope, target share, snap %.

  • POST/api/newsletter/subscribeTry it →

    subscribe to the newsletter

    add an email to the newsletter_subscribers table.

Tools

Trade analysis, player signal grading, historical trend and DFS practice tools, projections, rankings, and trends. Custom alerts and PDF reports are currently unavailable.

  • GET/api/alertsTry it →

    user's custom alerts (pro)

    User rule evaluation/delivery is paused; existing rows are retained.

  • POST/api/alertsTry it →

    create custom alert (pro)

    Paused until an evaluator and delivery worker are verified.

  • DELETE/api/alerts/{alert_id}Try it →

    delete a custom alert (pro)

    Paused without deleting the retained rule.

  • PUT/api/alerts/{alert_id}Try it →

    update a custom alert (pro)

    Paused without changing or deleting the retained rule.

  • GET/api/alerts/systemTry it →

    recent system-generated alerts (pro)

    return the most recent system-generated alerts for a season (breakout, injury, snap surge, etc.).

  • POST/api/dfs/optimizeTry it →

    historical nine-slot DFS practice optimizer (pro/demo)

    Build a historical practice lineup; salaries are not provider data.

  • POST/api/dfs/optimize-fullTry it →

    DFS lineup optimizer with salary data (pro)

    generate optimal DFS lineups under salary cap constraints (requires dfs_salaries data).

  • GET/api/dfs/salaries/{week}Try it →

    DFS salaries and values (pro)

    DFS player salaries with projected value for a given week.

  • GET/api/projectionsTry it →

    season projections list (pro)

    Lab Pass projection listing; free-launch/demo bypass is explicit.

  • GET/api/projections/player/{player_id}Try it →

    latest stored projection rows for one player (Lab Pass)

  • GET/api/projections/position/{position}Try it →

    positional projections for the week (pro)

    all weekly projections for a position, ranked by projected points. pro tier required.

  • GET/api/projections/season/{player_id}Try it →

    season-long projection (pro)

    season-long projection with risk assessment. pro tier required.

  • GET/api/projections/weekly/{player_id}Try it →

    detailed weekly projection (pro)

    detailed weekly projection with floor/ceiling. pro tier required.

  • GET/api/rankingsTry it →

    convenience alias — overall weekly rankings (public)

    Convenience alias for /weekly, capped at the public top 20.

  • GET/api/rankings/fullTry it →

    full rankings with tiers — all positions or filtered (pro)

    full rankings with tier assignments, floor/ceiling, notes — pro only. this endpoint is called by the frontend rankingsApi.getFull() method.

  • GET/api/rankings/weeklyTry it →

    overall weekly rankings across all positions (public)

    top 20 overall rankings across all positions — free tier.

  • GET/api/rankings/weekly/{position}Try it →

    top 20 positional rankings (public)

    top 20 per position — free tier. returns name, rank, projected points.

  • GET/api/rankings/weekly/{position}/fullTry it →

    full positional rankings with tiers (pro)

    full positional rankings with tier assignments, floor/ceiling, notes.

  • GET/api/reports/weekly/{week}Try it →

    planned weekly report PDF endpoint; currently unavailable

    Weekly analysis report PDFs are not currently implemented. This endpoint returns 404 instead of serving a placeholder file. Previous behavior served a literal '%PDF-1.4 placeholder' byte string as a real download — removed 2026-06-10 (zero-fake-data rule).

  • POST/api/tools/bench-analyzerTry it →

    selected-player distribution sum — computes P10/P50/P90 under an independence approximation and per-player variance contribution. Every selected player is included; this is not lineup selection.

    compute team-level distribution from each player's empirical history.

  • GET/api/tools/compareTry it →

    side-by-side player comparison for trade evaluation, draft-day decisions, or weekly start/sit. assembles composite rank + eligible external expert/consensus and market/trade ranks + distribution P10/P50/P90 + 2026 projection + predictive leaderboard ranks + last-5 games + drivers, then computes per-axis A/B/TIE/N/A winners and an overall verdict (only when >= 3 axes have data on both sides).

    head-to-head comparison payload — see service for the per-axis logic. NEVER fabricates winners. when either side lacks data on an axis, that axis returns winner='N/A' and is excluded from the overall verdict. cross-position comparisons (RB vs WR) include a 'projection_vs_replacement' axis that normalizes raw points against each player's positional replacement baseline so the verdict isn't biased toward WRs. dynasty mode (``format=dynasty``) pulls KTC values from expert_rankings (notes ktc_value=NNNN). NEVER fabricates dynasty values — when a player has no KTC row we surface dynasty_value=null with source='unavailable'.

  • GET/api/tools/dst-streamingTry it →

    weekly streaming defense leaderboard — composite of opp implied total + wind + opp YTD turnovers + def YTD sacks/INTs (analysis 258)

    top-N defenses to stream this week, ranked by composite streaming score.

  • GET/api/tools/dynasty-rookiesTry it →

    2026 dynasty rookie tier sheet — draft capital + landing spot + athletic profile + college production blended across available inputs, then bucketed into 5 relative quantiles

    tier-sheet of every rookie in the 2026 class. drafted players are hydrated from wikipedia's actual draft results; skill-position rookies have college production fields populated from each player's wikipedia article when available. unknown numeric fields stay null with college_data_status='unavailable'. Missing component weights are renormalized rather than neutral-imputed. Per-component source availability and weighted input coverage are returned on every row. Tiers are class-relative quantiles, not calibrated outcome forecasts.

  • GET/api/tools/lineup-advisorTry it →

    historical game-environment browser using archived wind, closing lines, and recent scoring-format usage

    Return descriptive historical environment buckets, not lineup picks.

  • POST/api/tools/mock-draft/{draft_id}/finishTry it →

    finalize draft and return a coverage-aware report + roster summary

    Compute the user's final report, including: * H2H VBD grade, or a coverage-gated historical best-ball grade * VBD vs league average * top 3 strengths + top 3 weaknesses with explanations * comparable real-life draft template (e.g. Hyper-RB, Zero-RB) * league rosters with starter assignments * improvement suggestions for next year

  • POST/api/tools/mock-draft/{draft_id}/pickTry it →

    record user pick, then auto-advance AI picks until user is back on the clock

    record the user's pick. the service then runs AI picks forward until either the user is on the clock again or the draft is complete.

  • GET/api/tools/mock-draft/{draft_id}/stateTry it →

    get current draft state — picks, on-the-clock, top-30 available players

    fetch the current state of an in-progress mock draft.

  • POST/api/tools/mock-draft/startTry it →

    start a mock draft — sets up league config and runs AI picks until user is on the clock

    create a new mock draft. body keys: teams, scoring, format, slot, rounds. returns the full draft state with the user on the clock for their first pick. ``format`` accepts ``h2h`` (default), ``best_ball``, or the legacy ``snake`` alias for h2h. Best-ball drafts default to 18 rounds and strip K/DST from the pool (per Bible Ch14 §1).

  • GET/api/tools/predictive-leaderboardsTry it →

    predictive metrics leaderboards — surfaces YPRR / TPRR / target-share / air-yards-share / aDOT / YACO-over-baseline. open-source proxies; PFF/SIS/Fantasy Points have proprietary versions

    leaderboard payload for one metric/position/season. v1 proxies — see is_proxy.

  • GET/api/tools/predictive-leaderboards/metricsTry it →

    metadata for every metric exposed by predictive-leaderboards

    returns {metrics: [...]} for the frontend dropdown.

  • GET/api/tools/redzone-carriesTry it →

    inside-the-10 carry share leaderboard — surfaces who actually gets the goal-line work (73.7% of rushing TDs come from inside the 10)

    inside-the-10 / inside-the-5 / goal-to-go carry share + TD efficiency, per RB or QB.

  • GET/api/tools/saved-tradesDeprecatedTry it →

    saved-trade server persistence is not available

    Frontend saved trades are browser-local; do not pretend the API stored them.

  • GET/api/tools/slot-defense-rankingsTry it →

    32-team slot defense ranking (Bible Ch09 §18) — 1=toughest, 32=softest

    full 32-team slot defense ranking for a season.

  • GET/api/tools/slot-matchupsTry it →

    retrospective slot WR context using completed-season defense ranks, receiver profiles, and realized selected-game outcomes

    Retrospective slot WR context for one completed historical week. This is not point-in-time start/sit advice: the defense ranks and receiver profiles use the completed season, and the weekly rows include realized game usage/results. It is also a team-level proxy, not a per-CB grade.

  • GET/api/tools/sosTry it →

    per-NFL-team strength of schedule by fantasy position. SOS = avg opponent FP-allowed-per-game vs the position across the schedule (analysis 261). A 2026 request distinguishes a missing schedule from a loaded schedule whose positional analysis has not been generated.

    returns per-team SOS, defense rankings, and weekly heatmap rows.

  • POST/api/tools/start-sitTry it →

    weekly per-player signal grader — combines available projection, weather, matchup, usage, and consistency signals into one verdict per player. accepts EITHER {player_ids:[...]} (new recommender) OR {roster:[{slot,player_id},...]} (legacy lineup optimizer).

    polymorphic body: * NEW shape: ``{"player_ids": [421, 2189, ...]}`` → returns the Start/Sit recommender response (projection, wind/Vegas, week-bounded history, leaderboards, and consistency synthesized into START / SIT / FLEX_OK / FADE). Completed-season Slot Matchups hindsight is excluded. * LEGACY shape: ``{"roster": [{"slot":"QB","player_id":"...."}], "scoring":"...", "week":...}`` → returns the legacy lineup optimizer response (used by the older StartSitBuilder UI).

  • GET/api/tools/streaming-kickersTry it →

    weekly streaming kicker leaderboard — composite of team implied total + opp red-zone FG-lean + wind + kicker FG% (analysis 260)

    top-N kickers to stream this week, ranked by composite streaming score.

  • POST/api/tools/trade-analyzerTry it →

    evaluate a fantasy trade — v2 (composite-v2 + projections + VBD + drivers). polymorphic body: pass {team_a_gives,team_b_gives} for the v2 shape, or legacy {team_gives,team_gets} for the older trade_service explanation+verdict response.

    polymorphic body — see summary.

  • GET/api/tools/trade-finderTry it →

    find up to 5 generic value-balanced candidate packages for the players you're sending out. uses the same VBD primitives as the trade analyzer and a bounded top-ranked candidate pool. this endpoint does not know league rosters, player availability, or manager needs. positive give-side VBD uses a ±10% band; nonpositive VBD uses an absolute ±5 VBD window. ranks by score = 0.5*value_match + 0.3*positional_fit + 0.2*tier_upgrade. returns each trade with give[], receive[], drivers, fairness rating, and an explicit candidate-pool limitation.

    find up to 5 realistic trade packages for the give-side players. This is a generic rankings-based candidate scan, not a league trade market. Positive give-side VBD uses a relative ±10% band; nonpositive VBD uses an absolute ±5 window to avoid division by zero.

  • GET/api/tools/trap-gamesTry it →

    trap-game leaderboard — surfaces team-weeks where an easy opponent is sandwiched between hard ones (lookahead/letdown), often on short rest. opponent strength comes from team_win_baselines (Sharp Football). schedule mechanics layered on top: short rest, divisional, road, standalone primetime. methodology selectable; defaults to hometeam_textbook_v1. Empty responses distinguish missing schedule data from a computed zero-candidate result.

    returns sortable trap-game rows + a full league-by-week grid.

  • GET/api/tools/waiver-rankerTry it →

    historical usage-trend watchlist with illustrative FAAB ranges — GET

    find trending waiver wire targets based on recent performance data (GET).

  • POST/api/tools/waiver-rankerTry it →

    historical usage-trend watchlist with illustrative FAAB ranges — POST

    find trending waiver wire targets based on recent performance data (POST).

  • GET/api/tools/waiver-trendTry it →

    snap + route + target + carry share trend leaderboard — ranks by 4-game OLS slope (leading indicator of fantasy points). WAIVER GEMs = STRONG_UP outside top-150 by season fantasy_pts_ppr

    opportunity-trend leaderboard for one season. The waiver wire is won by spotting opportunity changes BEFORE they convert to fantasy points. Snap, route, target, and carry share trending up are leading indicators. We rank by 4-game slope, not weekly raw values.

  • GET/api/trends/{player_id}Try it →

    trend analysis — target share, snap %, usage (pro)

    rolling trend data for a player — target share, snap %, usage rate, fantasy output.

  • GET/api/trends/trendingTry it →

    dashboard trending players (pro)

    find players with the biggest positive or negative trend over the last 4 weeks.

ScrimmageChat / Forge

ScrimmageChat has labeled database-backed fallback. The separate ForgeStat SSE endpoint is unavailable until its upstream is configured and verified.

  • GET/api/forge/analyzeTry it →

    unavailable ForgeStat SSE integration

    The separate ForgeStat upstream is not release-configured or verified.

  • POST/api/tools/forge-chatTry it →

    ScrimmageChat research assistant — uses Hermes web research only when that deployment integration is enabled; otherwise returns labeled database-backed analysis or a degraded response

    Answer a fantasy question with explicit source/degradation metadata.

League Import

Import rosters and league settings from supported fantasy platforms or universal manual import. Draft Monkeys currently supports account linking and Silverback/Monkey Kong entitlement only; its league-data import is paused.

  • POST/api/cbs-import/rosterTry it →

    import cbs sports roster from pasted text

    import a roster from cbs sports by pasting exported csv/text. cbs allows exporting rosters as csv. paste the contents here and we'll match players against our database. accepts formats like: - "Patrick Mahomes,QB,KC" - "Patrick Mahomes\tQB\tKC" - one player per line, any reasonable format

  • GET/api/dm/import/{league_id}Try it →

    import a Draft Monkeys league

    Report the unavailable partner import honestly.

  • GET/api/dm/leaguesTry it →

    list Draft Monkeys leagues for the authenticated user

    Report the unavailable partner import honestly.

  • GET/api/espn/league/{league_id}Try it →

    get ESPN league info

    Fetch a public league without accepting credentials in the URL. Private leagues use ``POST /league/{league_id}/lookup`` so ESPN cookies remain in the request body.

  • POST/api/espn/league/{league_id}/importTry it →

    import your ESPN team roster

    import your team's roster from an ESPN league. matches espn players against our nfl_players table using espn_id first, then falling back to name matching. returns the full roster with match status and team record. for private leagues, include espn_s2 and swid in the request body.

  • POST/api/espn/league/{league_id}/lookupTry it →

    get ESPN league info (private-safe body)

    Fetch public or private league metadata with cookies in the body.

  • GET/api/espn/league/{league_id}/rostersTry it →

    get all rosters in an ESPN league

    Fetch public-league rosters without URL credentials. Private leagues use the POST variant of this route.

  • POST/api/espn/league/{league_id}/rostersTry it →

    get ESPN rosters (private-safe body)

    Fetch rosters with any private-league cookies in the request body.

  • GET/api/fantrax-import/league/{league_id}DeprecatedTry it →

    Fantrax league-ID import unavailable; use manual paste

    The previously guessed public API contract is rejected by Fantrax.

  • POST/api/fantrax-import/manualTry it →

    manual fantrax roster import from pasted text

    manual fantrax roster import — paste roster data from fantrax csv export. use this when the api can't access the league. accepts any reasonable text format with player names.

  • POST/api/fleaflicker/import/{league_id}/{team_id}Try it →

    import a fleaflicker roster

    import a team's roster from fleaflicker, matching players to our db. fetches the roster and league standings from fleaflicker, then matches each player against our nfl_players table by name. returns the full roster with match status, team record, and league info.

  • POST/api/fleaflicker/leaguesTry it →

    find fleaflicker leagues by email

    fetch all nfl leagues for a fleaflicker user by email. fleaflicker's api is public — no password or auth token needed. returns league id, name, and the user's team id in each league.

  • GET/api/fleaflicker/roster/{league_id}/{team_id}Try it →

    get a fleaflicker team roster

    fetch a team's roster from a fleaflicker league. returns player names, positions, teams, and lineup slots.

  • POST/api/import/universalTry it →

    universal roster import — any platform, any format

    import a roster from any fantasy platform by pasting text/csv. this is the catch-all fallback that works with any platform. smart player name matching handles common formats: - "Patrick Mahomes, QB, KC" - "Mahomes KC QB" - "1. Patrick Mahomes (QB) - KC" - tab/csv/pipe-delimited tables - any mix of the above returns matched players with confidence scores (0.0-1.0): - 1.0 = exact match - 0.85+ = high confidence - 0.5-0.85 = medium confidence (review recommended) - <0.5 = low confidence (likely wrong)

  • GET/api/leagues/import/{league_id}Try it →

    Import League

    import a user's roster from a sleeper league.

  • GET/api/leagues/searchTry it →

    Search User

    find a sleeper user by username.

  • GET/api/leagues/sleeper/user/{username}Try it →

    Search User By Path

    find a sleeper user by username (path param convenience route).

  • GET/api/leagues/user/{user_id}/leaguesTry it →

    List Leagues

    list all nfl leagues for a sleeper user.

  • GET/api/mfl/league/{league_id}Try it →

    get MFL league info

    fetch league name, settings, scoring, and franchise list from MFL.

  • POST/api/mfl/league/{league_id}/importTry it →

    import a franchise roster from MFL

    import a specific franchise's roster from an MFL league. matches MFL player names against our nfl_players table and returns the match result without saving it to the user's account. body: - franchise_id: the MFL franchise identifier (e.g. "0001") - year: season year (default 2026) The upstream host is fixed to api.myfantasyleague.com; clients cannot provide or override a network destination.

  • GET/api/mfl/league/{league_id}/rostersTry it →

    get all MFL league rosters

    fetch all team rosters with MFL player IDs.

  • GET/api/nfl-import/league/{league_id}Try it →

    import nfl.com fantasy league via api

    import a league from nfl.com fantasy football. tries the nfl fantasy api first (public leagues). if the api is unavailable or the league is private, returns instructions for manual import via POST /api/nfl-import/manual. nfl.com uses GSISIDs which we cross-reference for high-confidence matching.

  • POST/api/nfl-import/manualTry it →

    manual nfl.com roster import from pasted text

    manual nfl.com roster import — paste roster data from nfl.com. use this when the api can't access the league (private leagues). accepts any reasonable text format with player names.

  • POST/api/rts/importTry it →

    import roster from pasted RTSports data

    import a roster from pasted text (CSV, tab-delimited, or plain text). RTSports allows users to export or copy their roster data. paste it here and we'll parse player names, match them against our nfl_players table, and return a structured roster. accepted formats: - "QB Patrick Mahomes KC" - "Patrick Mahomes, QB, KC" - "Patrick Mahomes\tQB\tKC" - one player name per line

  • GET/api/rts/league/{league_id}Try it →

    get RTSports league info

    try to fetch league info from RTSports. RTSports api access is limited — this may return a partial result with a suggestion to use the roster paste import instead.

  • POST/api/yahoo/import-manualTry it →

    import Yahoo roster manually

    import a Yahoo Fantasy roster by manually entering player names. this is the fallback for when yahoo oauth isn't available. users can copy their roster from yahoo's website and paste the player names here. each player needs at minimum a `name` field. position and yahoo_player_id are optional but improve matching accuracy. example request body: ```json { "league_name": "My Yahoo League", "team_name": "Team Awesome", "league_id": "123456", "players": [ {"name": "Patrick Mahomes", "position": "QB", "slot": "QB"}, {"name": "Derrick Henry", "position": "RB", "slot": "RB"}, {"name": "CeeDee Lamb", "position": "WR", "slot": "WR"}, {"name": "Travis Kelce", "position": "TE", "slot": "TE"}, {"name": "Josh Allen", "position": "QB", "slot": "BN"} ] } ```

  • GET/api/yahoo/league/{league_key}Try it →

    get Yahoo league info

    Return manual-import guidance for a Yahoo league key. Raw OAuth tokens are intentionally not accepted by this route (especially not in its URL). A future Yahoo OAuth integration must use a server-side authorization-code flow and encrypted token storage. accepts league_key in multiple formats: - nfl.l.123456 - 449.l.123456 - just the numeric id: 123456 - full url: https://football.fantasysports.yahoo.com/f1/123456

Stripe & Billing

Lab Pass subscription management — checkout, billing portal, subscription status, and webhook ingestion.

  • GET/api/admin/dm-containment-metricsTry it →

    admin-only Draft Monkeys containment counters

    Expose only fixed-cardinality, identifier-free process counters.

  • POST/api/stripe/create-checkoutTry it →

    start a stripe checkout session

    Create or recover one durable, user-scoped Checkout attempt.

  • POST/api/stripe/create-portalTry it →

    open the stripe billing portal

    returns ``{portal_url}`` or the not-configured payload. auth is optional only so the not-configured branch can be reached without a session (the QA curl in PART D doesn't carry a token). once stripe is configured we still require an authenticated user.

  • POST/api/stripe/reconcileTry it →

    admin-only Stripe subscription reconciliation

    Compare canonical rows with Stripe; mutate only with explicit apply=true.

  • POST/api/stripe/webhookTry it →

    receive stripe webhook events

    Verify a signature and update subscription entitlement state. An entirely unconfigured local environment is acknowledged as inactive. Any partial or explicitly disabled live-looking configuration returns 503 so Stripe retries instead of losing an event or mutating entitlements while the release safety switch is off.

  • GET/api/subscription/statusTry it →

    current subscription tier + period end

    Return the exact plan, lifecycle, provenance, and portal capability. safe to call without auth — anonymous callers get the free tier shape so the marketing pricing page can read ``configured`` without 401ing.

Auth & Account

Registration, login, token refresh, dashboard aggregation, search, and exports.

  • POST/api/auth/change-passwordTry it →

    change current user password

    Verify the current password, then replace it with a new password.

  • POST/api/auth/dm-linkTry it →

    link a Draft Monkeys account to the logged-in user

    attach a Draft Monkeys identity to the current (SL-authenticated) account so DM login works for it from then on. requires being logged in with ScrimmageLab credentials — that's what makes it safe.

  • POST/api/auth/dm-loginTry it →

    log in with a Draft Monkeys account

    exchange a Draft Monkeys (supabase) access token for ScrimmageLab tokens. verifies the token against DM's published signing keys, then links or provisions the matching ScrimmageLab account.

  • POST/api/auth/forgot-passwordTry it →

    request a password-reset email

    Always returns 200 with the same body whether or not the account exists (don't leak account existence). Sends a 1-hour single-use reset link via email when the account is real and email is configured.

  • POST/api/auth/loginTry it →

    log in

    validate credentials and return tokens.

  • POST/api/auth/logoutTry it →

    revoke the current refresh session

    Revoke the refresh-token family so copied tokens cannot rotate again.

  • GET/api/auth/profileTry it →

    get current user profile

    fetch the authenticated user's full profile.

  • PATCH/api/auth/profileTry it →

    update current user profile

    Persist the authenticated user's editable profile fields.

  • POST/api/auth/refreshTry it →

    refresh access token

    exchange a valid refresh token for a new access + refresh pair.

  • POST/api/auth/registerTry it →

    register new user

    create a new free-tier account and return tokens.

  • POST/api/auth/reset-passwordTry it →

    set a new password using a reset token

    Complete a password reset. The token is bound to the current password hash, works once, and expires after 1 hour.

  • GET/api/dashboardTry it →

    aggregated dashboard data

    return trending players, alerts, top pickups for the dashboard.

  • GET/api/export/dynasty-rookies.csvTry it →

    2026 dynasty rookie tier sheet export

    csv export of the 2026 rookie tier sheet from rookie_tier_service. columns: ``tier,tier_label,position,name,team,draft_round,draft_pick, capital_tier,dynasty_score,input_coverage_pct,missing_components, imputed_components,draft_capital,landing_spot,athletic_profile,production, position_premium and per-component availability fields. Missing component scores are blank and are never exported as neutral placeholders.

  • GET/api/export/players.csvTry it →

    verified current fantasy-player pool export

    CSV export of the active bounded player pool (QB/RB/WR/TE/K). Columns start with the immutable pool rank/release/generated/cutoff provenance, followed by player identity, verified team, bio, bye and observed-status fields.

  • GET/api/export/rankings.csvTry it →

    public composite cheat-sheet export

    Public CSV cheat sheet of the latest forgestat composite ranking. columns: ``overall_rank,position_rank,name,position,team,tier,bye_week`` only rows from the canonical composite ranker (v2 with v1 fallback) are emitted; we DO NOT fabricate ranks. Projection values remain on gated projection surfaces and are intentionally absent from this public export.

  • GET/api/searchTry it →

    global search across players, articles, teams, tools

    aggregated search for the site-wide header search bar. returns up to 5 players, 3 articles, 2 teams, and matching tools. caps are fixed (not derived from ``limit``) so each result group always renders predictably regardless of the slider.

Other

Endpoints that did not match a primary category — admin, health, and uncategorized routes.

  • POST/api/admin/agent-artifactsTry it →

    agent pushes daily review artifacts (machine token)

  • POST/api/admin/agent-artifacts/publish-approvedTry it →

    agent publishes one immutable ADMIN-approved tier manifest

  • GET/api/admin/agent-reviewTry it →

    review queue for the rankings agent (admin)

  • POST/api/admin/agent-review/{item_id}/statusTry it →

    mark a review item reviewed (admin)

  • POST/api/admin/agent-review/tier-publications/{approval_id}/publishTry it →

    publish one immutable approved tier manifest (admin)

  • POST/api/admin/agent-review/tier-publications/approveTry it →

    approve an exact previewed tier publication (admin)

  • POST/api/admin/agent-review/tier-publications/previewTry it →

    validate and preview one complete tier run (admin)

  • GET/api/admin/content/queueTry it →

    articles pending publication (admin)

    articles in draft / review / scheduled states.

  • GET/api/admin/pipeline/healthTry it →

    live pipeline health from ingestion logs (admin)

  • GET/api/admin/pipeline/statusTry it →

    data pipeline health (admin)

    Return the latest recorded result for every ingestion source/table.

  • POST/api/admin/pipeline/triggerTry it →

    manually trigger data refresh (admin)

    Dispatch one or more real Celery tasks and return their result id.

  • GET/api/admin/subscribersTry it →

    subscriber count and metrics (admin)

    Return measurable account metrics without inventing Stripe analytics.

  • GET/api/draft-assistant/{assistant_id}/availableTry it →

    search undrafted players

  • POST/api/draft-assistant/{assistant_id}/pickTry it →

    record the on-the-clock pick

  • GET/api/draft-assistant/{assistant_id}/recommendationsTry it →

    best available for your next pick

  • GET/api/draft-assistant/{assistant_id}/stateTry it →

    current draft state

  • POST/api/draft-assistant/{assistant_id}/sync-sleeperTry it →

    ingest new picks from the sleeper draft

  • POST/api/draft-assistant/{assistant_id}/undoTry it →

    undo the most recent pick

  • GET/api/draft-assistant/import-settingsTry it →

    import league settings for the assistant (pro)

    Fetch authorized/public league settings in the assistant's schema.

  • POST/api/draft-assistant/startTry it →

    start a live draft assistant session (pro)

  • POST/api/feedbackTry it →

    submit feedback anonymously or with an account

  • GET/api/feedback/adminTry it →

    list feedback (admin)

  • GET/api/feedback/admin/{feedback_id}Try it →

    feedback detail (admin)

  • PATCH/api/feedback/admin/{feedback_id}Try it →

    update feedback (admin)

  • POST/api/feedback/admin/{feedback_id}/replyTry it →

    reply to feedback (admin)

  • GET/api/feedback/ai-queueTry it →

    claim feedback for Hermes review

  • POST/api/feedback/ai-reviewsTry it →

    save Hermes feedback review

  • GET/api/feedback/mineTry it →

    my feedback history

Spec endpoint: /openapi.json · Interactive: /docs · /redoc

Catalog rebuilt hourly from the live OpenAPI spec — never manually maintained.