# Bloodline Bowl Fantasy Football Intelligence Bridge > A read-only JSON bridge that turns multiple Sleeper (and, once authorized, Yahoo) fantasy football leagues into self-describing documents an AI assistant can fetch and reason about: rosters, scoring, projections, draft help, and a weekly decision engine (lineup / start-sit / matchup / waivers). Production base URL: https://bloodline-bowl-sleeper-bridge.vercel.app GitHub repository (methodology only, not required): https://github.com/supyo29/bloodline-bowl Read-only: yes. No auth required for public leagues. ## Start here Canonical discovery contract (machine-readable): https://bloodline-bowl-sleeper-bridge.vercel.app/api/ai Compact link index (every URL absolute and concrete, current week filled in — for browsing tools that cannot resolve relative paths or templates): https://bloodline-bowl-sleeper-bridge.vercel.app/api/ai/compact Human-readable overview: https://bloodline-bowl-sleeper-bridge.vercel.app/ai Fetch /api/ai first. It returns the full service map: leagues, known managers, every capability, and concrete route templates. Follow the links it returns — do not guess or normalize URLs. Routes span several namespaces (/api/leagues/..., /api/league/..., /api/context/..., /api/intelligence/..., ...); 'canonical' means 'the advertised route', not 'one prefix'. HTTP 200 means only that the route resolved. Always check the response body's status / warnings / data_quality / *_status fields — a capability can return 200 and still be BLOCKED, DEGRADED, AUTH_REQUIRED, PERSISTENCE_NOT_CONFIGURED, or UNSUPPORTED_MODE. ## Routing hierarchy (canonical) /api/ai -> /api/leagues -> /api/leagues/{leagueSlug} -> /api/leagues/{leagueSlug}/managers -> /api/leagues/{leagueSlug}/managers/{managerSlug} -> specific analysis capability ## Identity rule League identity != manager identity. The league slug selects the league; the manager slug selects a team owner INSIDE it. Membership is validated live. A non-member manager returns a 4xx error, never a different manager. There is no cross-league fallback. Given only a manager username, find its league in the known-manager list below (or via /api/leagues/{leagueSlug}/managers), then descend league -> manager -> capability. ## Leagues - bloodline-bowl (Bloodline Bowl) — provider: sleeper, status: READY, default — https://bloodline-bowl-sleeper-bridge.vercel.app/api/leagues/bloodline-bowl - devoted-to-the-game (Devoted to the Game) — provider: sleeper, status: READY — https://bloodline-bowl-sleeper-bridge.vercel.app/api/leagues/devoted-to-the-game - sportys-alumni (Sporty's Alumni) — provider: sleeper, status: READY — https://bloodline-bowl-sleeper-bridge.vercel.app/api/leagues/sportys-alumni - maclin-on-chicks-xvi (Maclin on Chick's XVI) — provider: yahoo, status: LIVE_VALIDATION_REQUIRED — https://bloodline-bowl-sleeper-bridge.vercel.app/api/leagues/maclin-on-chicks-xvi - rogers-park (Rogers Park) — provider: yahoo, status: LIVE_VALIDATION_REQUIRED — https://bloodline-bowl-sleeper-bridge.vercel.app/api/leagues/rogers-park ## Known manager routes - supyo29 (Sleeper: Supyo29) — league bloodline-bowl — https://bloodline-bowl-sleeper-bridge.vercel.app/api/leagues/bloodline-bowl/managers/supyo29 - bijimac (Sleeper: BijiMac) — league bloodline-bowl — https://bloodline-bowl-sleeper-bridge.vercel.app/api/leagues/bloodline-bowl/managers/bijimac - darthmarker (Sleeper: DarthMarker) — league devoted-to-the-game — https://bloodline-bowl-sleeper-bridge.vercel.app/api/leagues/devoted-to-the-game/managers/darthmarker ## Analysis capabilities - League discovery [service]: /api/leagues — Every configured league with its canonical slug, provider, readiness, and the URLs to descend into it. - League overview [league]: /api/leagues/{leagueSlug} — One league: settings, teams, managers, standings, draft status, plus a live-verified roster_id → canonical manager URL table. - Manager directory [league]: /api/leagues/{leagueSlug}/managers — Every manager in one league (live from the provider) with canonical manager, draft, and snapshot URLs. - Manager home + roster [manager]: /api/leagues/{leagueSlug}/managers/{managerSlug} — One manager's verified identity, full roster (starters / bench / taxi / reserve), roster composition, slot coverage, and links to every manager-specific capability. - Manager analytical context [manager]: /api/context/{leagueSlug}/{managerSlug} — Provider-independent canonical context for one manager: canonical ids, team, roster, record. The generic spine the weekly engine consumes. - Canonical league state [league]: /api/league/{leagueSlug}/state — Provider-independent current-state snapshot for one league (the same shape the nightly capture job persists), with explicit live + persistence status. - Scoring rules + analysis [league]: /api/leagues/{leagueSlug}/scoring — League scoring settings, derived metrics, archetype examples, and sensitivity diagnostics. - League projections [league]: /api/leagues/{leagueSlug}/projections — Season projections translated through this league's actual scoring, with value-over-replacement, tiers, and positional scarcity. Identical for every manager in the league. - Single-player projection [league]: /api/leagues/{leagueSlug}/projections/{playerId} — One player's projection detail under this league's scoring. - Need-weighted manager projections [manager]: /api/leagues/{leagueSlug}/managers/{managerSlug}/projections — League projections re-weighted for ONE manager's roster: contextual_value, roster_fit, need_multiplier, and an RI-vs-Sleeper projection edge. - League draft state [league]: /api/leagues/{leagueSlug}/draft — Shared draft board: picks made, budgets / max bids (auction) or board order (snake), and available players. - Personalized draft context [manager]: /api/leagues/{leagueSlug}/managers/{managerSlug}/draft — Shared draft state composed with one manager's roster, slot, picks, positional needs, and best-available candidates. - Snake-draft recommendation engine [manager]: /api/leagues/{leagueSlug}/managers/{managerSlug}/recommendations — Who THIS manager should draft now — turn geometry, tier cliffs, ADP survival, reach cost, roster-construction risk, two-pick optimisation. Snake drafts only. - League snapshot [league]: /api/leagues/{leagueSlug}/snapshot — Compact, AI-friendly current-state view of the whole league in one document. - Personalized snapshot [manager]: /api/leagues/{leagueSlug}/managers/{managerSlug}/snapshot — Shared league snapshot composed with one manager's roster, slot, picks, needs, and recommendations — a single paste-once hand-off URL. - Weekly intelligence (combined decision layer) [manager-week]: /api/intelligence/{leagueSlug}/{managerSlug}/week/{week} — Lineup + start/sit + matchup + leverage + waivers for one manager and week, plus top_actions and a manager-facing summary. Missing projections degrade explicitly, never to 0. Waiver actionability alone is gated on the canonical free_agent_pool capability: when it is unavailable there is no WAIVER top_action and summary.waiver_priority states the pool is not materialized, while lineup / start-sit / matchup / Football-Intelligence / positional-needs are unaffected. - Optimal lineup + start/sit [manager-week]: /api/lineup/{leagueSlug}/{managerSlug}/week/{week} — Optimal legal starting lineup (slot assignment, not a points sort) for one manager and week, plus explicit start/sit comparisons for close calls. - Matchup analysis [manager-week]: /api/matchup/{leagueSlug}/{managerSlug}/week/{week} — Both teams on their best legal projected lineup: totals, margin, positional edges, leverage / swing players, bench depth, and (when coverage supports it) a seeded Monte-Carlo win probability. - Waiver / add-drop engine [manager-week]: /api/waivers/{leagueSlug}/{managerSlug}/week/{week} — League-aware acquisition engine: every candidate paired with the drop it requires, DO_NOT_ADD when the wire is not worth it. Free agency is canonical, this-league availability only. Gated on the canonical free_agent_pool capability: until the provider free-agent pool is materialized/certified the response is status NOT_READY (HTTP 200, reason_code FREE_AGENT_POOL_UNAVAILABLE) with empty recommendations — UNROSTERED != CERTIFIED_FREE_AGENT, HTTP_200 != ACTIONABLE_DATA. - Transaction ledger [league]: /api/transactions/{leagueSlug} — Normalized canonical transactions for one league from the durable ledger (falls back to a live provider read before the first sync; `source` says which). - Historical weekly snapshots [league]: /api/history/{leagueSlug}/week/{week} — Retained weekly captures from the durable snapshot store (earlier versions are never destroyed). Explicit PERSISTENCE_NOT_CONFIGURED state when history is not wired up. - Provider + persistence readiness [service]: /api/providers — Live health of every fantasy provider and the persistence subsystem, from real probes. - Receiver target progression [service]: /api/football-intel/players/{playerId}/progression — Raw FTN read_thrown codes on actual receiver targets by NFL week: numeric codes RAW_0/RAW_1/RAW_2 (meaning UNVERIFIED — the source dictionary conflicts with observed data, so they are NOT labelled first/second/third read) plus CHECKDOWN, DESIGNED and SCRAMBLE_DRILL. DESCRIPTIVE_ONLY; contains only the thrown target's code, not the full or unthrown QB progression, so do not use it to answer 'was he the first read'. - Player-Scheme index + manifest [service]: /api/player-scheme — Phase 9 Player-Scheme Intelligence. SHARED_DESCRIPTIVE only: it never adjusts a projection or recommendation (fantasy_adjustment_enabled=false). Tier data is PRIOR_ONLY through the 2025 season (no live 2026 signal); the FTN read_thrown progression is exposed as raw RAW_0/RAW_1/RAW_2 codes with UNVERIFIED semantics. Index of the namespace with the served manifest and per-tier content identity. - Player-Scheme player profile [service]: /api/player-scheme/players/{playerId} — Phase 9 Player-Scheme Intelligence. SHARED_DESCRIPTIVE only: it never adjusts a projection or recommendation (fantasy_adjustment_enabled=false). Tier data is PRIOR_ONLY through the 2025 season (no live 2026 signal); the FTN read_thrown progression is exposed as raw RAW_0/RAW_1/RAW_2 codes with UNVERIFIED semantics. One player's spatial / charting / tendency profile. - Player-Scheme player-vs-defense descriptors [service]: /api/player-scheme/matchups/{playerId}/{opponent} — Phase 9 Player-Scheme Intelligence. SHARED_DESCRIPTIVE only: it never adjusts a projection or recommendation (fantasy_adjustment_enabled=false). Tier data is PRIOR_ONLY through the 2025 season (no live 2026 signal); the FTN read_thrown progression is exposed as raw RAW_0/RAW_1/RAW_2 codes with UNVERIFIED semantics. Descriptive player-by-opponent scheme overlap; Tier D interaction research is SHADOW_ONLY with a zero numeric adjustment. - Player-Scheme team offense profile [service]: /api/player-scheme/teams/{team}/offense — Phase 9 Player-Scheme Intelligence. SHARED_DESCRIPTIVE only: it never adjusts a projection or recommendation (fantasy_adjustment_enabled=false). Tier data is PRIOR_ONLY through the 2025 season (no live 2026 signal); the FTN read_thrown progression is exposed as raw RAW_0/RAW_1/RAW_2 codes with UNVERIFIED semantics. Team offensive tendency profile. - Player-Scheme team defense profile [service]: /api/player-scheme/teams/{team}/defense — Phase 9 Player-Scheme Intelligence. SHARED_DESCRIPTIVE only: it never adjusts a projection or recommendation (fantasy_adjustment_enabled=false). Tier data is PRIOR_ONLY through the 2025 season (no live 2026 signal); the FTN read_thrown progression is exposed as raw RAW_0/RAW_1/RAW_2 codes with UNVERIFIED semantics. Team defensive scheme profile. - League market state (who is actually acquirable) [league]: /api/league/{league}/market?week={week}&view={summary|pool} — READ-ONLY, provider-independent Market State: the verified free-agent / waiver pool with the evidence behind every answer. Yahoo availability is stated per player by Yahoo (FA = addable now, W = claim-only with a clear DATE); Sleeper availability is inferred from rosters + the transaction feed. UNKNOWN is never reduced to available. Readiness is reported as separate AXES (availability / valuation / transaction / recommendation) so a verified pool is usable while exact claim timing is only PARTIAL. ?view=summary (default) returns readiness, counts, acquisition rules, FAAB/priority per team, pending-claim visibility, game-lock semantics, pool pagination evidence and freshness; ?view=pool adds the verified players (filter with position=QB|RB|WR|TE|K|DEF and status=FA|W|UNKNOWN). Advisory only: Bloodline never adds, drops, claims or trades. - Roster health (league) [league]: /api/leagues/{leagueSlug}/roster-health — SHARED_CONTEXT roster fragility, depth and contingency conditions for every team in the league. Conditions inform; this is not a recommendation and never fabricates a remedy. - Roster health (manager) [manager]: /api/leagues/{leagueSlug}/managers/{managerSlug}/roster-health — SHARED_CONTEXT roster fragility, depth and contingency conditions for one manager. Conditions inform; this is not a recommendation and never fabricates a remedy. - Schedule planning (league) [league]: /api/leagues/{leagueSlug}/schedule-planning — SHARED_CONTEXT schedule / opponent-difficulty / playoff-window planning conditions for the league. Conditions inform; not a recommendation. - Schedule planning (manager) [manager]: /api/leagues/{leagueSlug}/managers/{managerSlug}/schedule-planning — SHARED_CONTEXT schedule / opponent-difficulty / playoff-window planning conditions for one manager. Conditions inform; not a recommendation. - Team-management orchestrator (league) [league]: /api/leagues/{leagueSlug}/orchestrate — ADVISORY_ONLY composition of team-state, roster-health, schedule-planning and shadow layers over ONE canonical snapshot per request. Conditions inform and shadow layers never influence production numbers. - Team-management orchestrator (manager) [manager]: /api/leagues/{leagueSlug}/managers/{managerSlug}/orchestrate — ADVISORY_ONLY composition of team-state, roster-health, schedule-planning and shadow layers for one manager over ONE canonical snapshot. Conditions inform and shadow layers never influence production numbers. - Start/Sit shadow evidence diagnostics [service]: /api/football-intel/startsit-evidence — READ-ONLY diagnostics for the SHADOW Start/Sit model (ri-startsit-2026.1, frozen, SHADOW_ONLY): evidence-gate state, capture-store durability/health and evidence counts by capture class (LIVE_CAPTURED / LIVE_POST_LOCK / LIVE_UNVERIFIED / HISTORICALLY_RECONSTRUCTED). Reports no outcome metrics and never changes deployment state. - Book-Ready evidence retrieval [service]: /api/evidence — READ-ONLY analytical retrieval of structured EvidenceBlocks (Phase 3.5C). ?capabilities=1 lists topics, required parameters and per-surface Book-Ready capability (current / history / comparison / decomposition / confidence / freshness / lineage / units / chart-readiness) and the refresh status of each artifact. ?topic=. Source-native values are preserved next to a normalized analysis class; confidence, sample support, freshness, deployment and predictive status are INDEPENDENT axes; units/scale are explicit per metric (values above 1 can be legitimate); every comparison states its population; history comes only from immutable published snapshots and is labelled; Opportunity Propagation is CONDITIONAL, never an unconditional projection; SHADOW and DESCRIPTIVE evidence is never presented as production-predictive. history=1 and comparisons=1 are opt-in. Never writes prose or changes any production recommendation; SHADOW model outputs (Start/Sit, matchup, Waiver 2.0) are exposed as SHADOW evidence, never as production output. - Competitive trade intelligence [league]: /api/trades/competitive — POST endpoint. SEPARATE from legacy mutual-benefit trade discovery: this optimizes the requesting manager's championship equity subject to the deal staying plausibly acceptable to the counterparty — the other manager's improvement is a cost, not an objective. Modes: 'evaluate' (one explicit proposal via give_assets / receive_assets / counterparty), 'negotiate' (base deal plus value-extraction / negotiation envelope), 'discover' (search for analytically positive direct trade candidates for the requester), 'strategy_path' (direct vs hold vs buy-and-hold vs bounded two-step vs no-action). Every trade carries BOTH a competitive_classification (STRONG_COMPETITIVE_BUY … REJECT — is it analytically attractive) and a transaction_readiness (NOT_RECOMMENDED / REVIEW_REQUIRED / EXPLORATORY / NEGOTIATION_WORTH_EXPLORING / TRANSACTION_READY — should you act on it now); a positive classification with LOW confidence or LOW acceptance is NEVER TRANSACTION_READY. discover may return analytically positive candidates while still recommending NO_ACTION because none is transaction-ready — that is not a contradiction. status NO_ACTION is a SUCCESSFUL result (HTTP 200), not an error or a not-ready state; status REVIEW_REQUIRED is preserved and never softened into a recommendation; confidence (VERY_LOW/LOW/MEDIUM/HIGH) and readiness are passed through, never upgraded. Opponent-threat calculations use exactly the roster identities in the current snapshot (co-managed teams are one participant, not two); a participant-set mismatch fails the competitive recommendation closed. Every response carries the source snapshot lineage (league_snapshot_id, generated_at, scoring/roster fingerprints, player-data version). Acceptance likelihood is heuristic (one real league trade exists); opponent threat is heuristic; market appreciation potential is speculative; early-season dynamic market evidence is preseason-only; multi-step trade paths are bounded to a maximum of two completed trades. READ-ONLY analytics — it never submits, accepts, or modifies a trade and never sends a message. ## Legacy compatibility `?league=` query-form routes (e.g. /api/league?league=bloodline-bowl) still work but are legacy. Prefer the canonical path routes above. Let /api/ai tell you which capabilities are only available in the legacy form.