Description
n8n-nodes-sleeper
> [!IMPORTANT]
> This is an unofficial community project and is not affiliated with, endorsed by, or
> sponsored by Sleeper or Blitz Studios.
n8n-nodes-sleeper is a read-only n8n community node for public Sleeper fantasy football,
basketball, and hockey data. It needs no credentials and has no runtime dependencies.
Status
The source repository is public at
github.com/christopherjnelson/n8n-nodes-sleeper.
NBA/NHL controls require package version 0.3.0 or newer. Check the installed package version if
the UI does not expose those controls. The four polling events are Draft Pick Made, Transaction
Created or Updated, League Status Changed, and NFL Week Changed.
Features
- 18 deterministic read operations across 14 resources
- Exact opaque string IDs, per-input execution, paired-item links on successful outputs from all 18 actions, and
continueOnFail() - Raw Sleeper response fields without hidden joins, enrichment, caching, or truncation
- Operation-specific NFL, NBA, and NHL public API scope with zero credentials and zero runtime dependencies
- Four Phase 1 polling triggers with first-run baselines and monotonic anti-replay state
usableAsTool: truefor n8n AI agents without bundling an AI dependency
Installation
n8n Cloud
Search for Sleeper from the node picker or canvas. The verified action node is available
in the n8n node catalog. The currently approved Cloud version may lag npm and may not include the
latest actions or Sleeper Trigger. Confirm the installed version in your environment before relying
on specific operations.
Self-hosted n8n
Where Community Nodes are supported, open Settings → Community Nodes and enter:
n8n-nodes-sleeper
The installer provides the latest version published to npm. NBA/NHL operations require package
version 0.3.0 or newer. Check the installed package version if the UI does not expose those
controls.
npm
Install the latest version published to npm:
npm install n8n-nodes-sleeper
The retained next selector follows the prerelease channel and may differ from stable:
npm install n8n-nodes-sleeper@next
For a reproducible install, confirm that the package registry lists the version before pinning it.
The NBA/NHL features require 0.3.0 or newer:
npm install n8n-nodes-sleeper@0.3.0
See the community-testing guide for requested test evidence and
privacy rules.
Local development
Clone this repository, install the locked development dependencies, and run:
pnpm install --frozen-lockfile
npm run dev
Open http://localhost:5690 manually. The task-runner broker uses port 5691. The CLI’s o
shortcut still targets 5678.
Do not install development builds into an active n8n service.
Credentials
No credentials are required. The node uses Sleeper’s public, read-only API and CDN endpoints.
Operations
| Resource | Operation | Required inputs | Optional inputs | Output shape |
| —————– | ——————- | —————————————— | —————————————————————————————————- | ————————————————– |
| User | Get | Username or User ID | — | One raw user object |
| League | Get | League ID | — | One raw league object |
| League | Get Many for User | User ID, Sport, Season | — | One item per league; an empty array emits no items |
| League User | Get Many | League ID | — | One raw participating-user item |
| Roster | Get Many | League ID | — | One raw roster item |
| Matchup | Get Many | League ID, Week | — | One raw item per roster side |
| Transaction | Get Many | League ID, Round or Week | — | One raw transaction item |
| Playoff | Get Bracket | League ID, Bracket Type | — | One raw bracket-matchup item |
| Traded Pick | Get Many | League ID | — | One league-scoped traded-pick item |
| Draft | Get | Draft ID | — | One raw draft object |
| Draft | Get Many for League | League ID | — | One raw item per associated draft |
| Draft | Get Many for User | User ID, NFL/NBA, Season | — | One item per user draft |
| Draft Pick | Get Many | Draft ID | — | One raw item per recorded pick |
| Draft Traded Pick | Get Many | Draft ID | — | One draft-scoped traded-pick item |
| Player | Get Many | Sport, Active Only, Output Mode | Position; collection: Team, Has Team, Player IDs, Output Fields; Return All/Limit; Sort By/Direction | One keyed map or one item per player-map entry |
| Player | Get Trending | NFL/NBA, Trend Type, Lookback Hours, Limit | — | One raw player-ID/count item |
| Sport | Get State | NFL, NBA, or NHL | — | One raw sport-specific state object |
| Avatar | Get URL | Avatar ID, Image Size | — | One validated { avatar_id, size, url } object |
Usernames can change. Save the stable user_id returned by User → Get for later user
lookups. League and draft IDs are opaque strings and must not be converted to numbers.
League users and rosters are separate API results; this node does not join them. **Matchup →
Get Many** emits one record per roster side and does not pair records sharing a matchup_id.
Transaction → Get Many uses Sleeper’s round path parameter, which commonly corresponds
to an NFL week; NBA round-to-week semantics are not inferred. Draft Traded Pick → Get Many is
draft-scoped; Traded Pick → Get Many is league-scoped. Unsafe numeric opaque IDs in the
draft-scoped traded-pick response are returned as exact strings to avoid JavaScript precision loss. Sport support is operation-specific. Player catalogs support NFL, NBA, and
NHL; trending supports NFL and NBA; user seasonal league and draft listings support NFL and
observed NBA results; sport state supports NFL, NBA, and NHL. Sleeper’s current documentation
still labels seasonal user listing routes NFL-only. NHL catalogs support active filtering, but
position filtering is hidden and rejected locally because tested NHL position queries returned
empty results. NHL trending and seasonal user league/draft support are not advertised. NBA
seasonal results are observed live behavior and retain the documentation caveat.
Usage examples
The repository includes importable, inactive workflows with no credentials:
Replace the clearly marked sample username before running the user-leagues example. The
examples are repository resources and are intentionally excluded from the npm tarball.
Community workflow examples
The separate Sleeper workflow collection
includes Preseason League Command Center and Daily Trending Players Digest to Discord.
Their own setup guides cover the additional n8n configuration and credentials they require.
Player data guidance
Player → Get Many returns Sleeper’s object keyed by player ID. The unfiltered response is
approximately 5 MB, so Sleeper recommends fetching it sparingly and generally no more than
once daily. Active Only sends the server-side active=true filter; Position sends a
server-side fantasy-position filter for NFL and NBA. Tested NHL position filters returned an
empty response, so Position is hidden and stale nonempty NHL values fail before a request. Sleeper
documents no single-player endpoint.
NFL and NBA Position use a static dropdown with readable names and Sleeper codes, including
Quarterback (QB) and Point Guard (PG); the default choice is All Positions (empty query
value). NFL choices are DB (defensive
back), DEF (team defense), DL (defensive line), K (kicker), K/P (kicker/punter), LB (linebacker),
LEO, LS (long snapper), OG (offensive guard), OL (offensive line), OT (offensive tackle), P
(punter), QB, RB (running back), TE (tight end), and WR (wide receiver). NBA choices are C
(center), DEF (team entry), PF (power forward), PG (point guard), SF (small forward), and SG
(shooting guard). Saved expressions remain intact when changing sports. To clear a stale NHL
Position, switch to NFL or NBA, choose All Positions, then switch back to NHL. NHL keeps
Position hidden and rejects any stale nonempty saved value locally.
Single Map, the default, emits the keyed object as one n8n item. One Item per Player
preserves each raw player object and map order, adding the string map key as player_id only
when that field is absent. The node performs no caching, deduplication, or static-data storage.
For repeated lookups, fetch a bounded dataset on a schedule and store it externally.
The optional Team, Has Team, Player IDs, and Output Fields controls are in the
player-options collection. They filter or project the fetched map locally; team matching ignores
case, player IDs are comma-separated exact map keys, and Has Team is off unless explicitly set
to true. Output Fields accepts comma-separated flat field names; blank keeps all fields.
Projection runs for both output modes and always retains player_id, falling back to the exact
map key if the player object has no ID. Return All defaults to true; when disabled, Limit
defaults to 50. The top-level Sort By control can use full_name, team, position, or
player_id, with ascending order by default. Sorting applies only to One Item per Player;
Player ID uses numeric-aware string ordering (for example, 200 sorts before 1000) without
converting IDs to numbers. The native map-entry order is retained when no sort is selected.
The node applies filters, then sort, then limit, then field projection. These controls run
locally after the player map is fetched; they do not reduce the API response downloaded from
Sleeper. They reduce the saved execution history and downstream items. Active and supported
position filters remain server-side. Position remains hidden and locally rejected for NHL.
Trending players and attribution
Player → Get Trending defaults to Adds, a 24-hour lookback, and 25 results. Results contain
raw player IDs and counts; the node does not fetch the player map or add names or rankings.
Sleeper requires attribution when you display or republish its trending-player data. Credit
Sleeper in the consuming application, page, report, or downstream output.
Rate guidance
Keep request frequency well below Sleeper’s documented limit of roughly 1,000 calls per
minute. Avoid polling static league or player data unnecessarily, and keep player queries
bounded with Active Only and Position whenever possible.
Error behavior
The action node validates required and controlled values before transport, then delegates HTTP
execution and service errors to n8n’s declarative request framework. Successful outputs from all
18 actions link to their source input item. Errors raised by n8n’s transport or continue-on-fail
handling follow n8n’s own error-item behavior and may not carry paired-item metadata. A successful
HTTP response with a null body becomes a focused not-found error; Sleeper has been observed to
return HTTP 200 with null for an unknown user. Invalid response shapes produce a focused
node-operation error. Empty array responses emit no fabricated placeholder item.
Troubleshooting
Confirm opaque IDs are passed as strings and controlled inputs use one of the choices shown in
the editor. Avatar → Get URL validates the image with a HEAD request, so a missing image or
CDN outage is reported as a request failure. Use the
issue forms for
reproducible defects and private vulnerability reporting
for security reports.
Privacy and public data
Sleeper exposes public user and league data without authentication. This node does not log in,
access private accounts, or request private endpoints. Workflows can still store, transform,
or forward returned public data, so workflow owners remain responsible for downstream data
handling and retention.
Community testing
Release feedback remains welcome from clean, supported self-hosted n8n environments. Follow the
community-testing guide, then use the
structured issue forms
for compatibility results, reproducible bugs, or feature requests. Report suspected security
issues only through
private vulnerability reporting.
AI-tool use
The node can be selected as an n8n AI tool. Operations remain deterministic and read-only, and
the package contains no AI runtime dependency. Give agents specific user, league, or draft IDs
and bounded player queries; do not ask an agent to infer private or unknown identifiers.
Compatibility
@n8n/node-cli 0.46.4These are tested versions, not a promise of compatibility with every version admitted by a
peer dependency range.
Limitations
Sport availability depends on the operation. NHL trending and NHL seasonal user league/draft
listings are not offered. Sleeper’s current docs still call user seasonal league/draft routes NFL
only; NBA results are live-observed and retain that caveat. NHL state omits fields available in
NFL/NBA state, so raw sport-specific state objects pass through without inferred values. No NBA or
NHL week trigger is included; only the existing NFL Week Changed trigger watches global state.
The package continues to omit authentication, lineup changes, adds/drops, trades, draft actions,
league-setting changes, chat, Sleeper Picks, paid contests, player search, single-player lookup,
composite standings, scoreboards, roster resolution, activity feeds, enrichment, and hidden caching.
Avatar → Get URL makes a HEAD request to the documented CDN URL before emitting it. The
operation therefore fails when the image is missing or the CDN is unavailable; it emits URL
metadata rather than binary image data.
Ordinary action operations use n8n declarative routing. The Sleeper Trigger remains programmatic
because polling compares validated responses with persisted state across scheduled invocations.
Development
pnpm install --frozen-lockfile
pnpm run validate
pnpm run typecheck
pnpm run lint
pnpm run format:check
pnpm run test
pnpm run build
pnpm run scan:source
pnpm run smoke:load
pnpm run package:check
pnpm run smoke:install
See CONTRIBUTING.md for scope and contribution rules,
docs/testing.md for automated checks,
docs/manual-testing.md for the editor smoke guide, and
docs/release-readiness.md for current release status and links to the
dated release record.
Release and provenance
Releases run from reviewed annotated version tags. GitHub Actions validates the exact tagged
source, publishes directly to npm with provenance through GitHub OIDC, verifies the published
package, and then creates the GitHub Release. Versions 0.1.1, 0.2.0, and 0.2.1 used the
former staged flow; see docs/releasing.md for the active procedure and
historical records.
Contributing
Contributions must preserve the read-only public-API scope, exact workflow values, zero runtime
dependencies, and all automated gates. Security reports follow SECURITY.md.
License
MIT. See LICENSE.
Attribution
Sleeper API data and names remain the property of their respective owners. Trending-data users
must provide the attribution required by Sleeper’s API documentation.
The node icon is the current Sleeper-controlled robot favicon, extracted without visual changes
from the multi-size icon served by Sleeper’s homepage. See branding documentation.
Non-affiliation
This project is unofficial. It is not affiliated with, endorsed by, sponsored by, or produced
by Sleeper or Blitz Studios. Sleeper owns the robot favicon used as the node icon; its inclusion
does not imply endorsement.
