Thumbnail Endpoint

Unified API: One endpoint that handles league thumbnails, team thumbnails, and matchup thumbnails.

Endpoints:

  • /:league/thumb[.png] - League thumbnail (dark gradient with logo)
  • /:league/:team/thumb[.png] - Team thumbnail (team color gradient with logo)
  • /:league/:team1/:team2/thumb[.png] - Matchup thumbnail (split design, 1440x1080)

Parameters

  • league - Sport league code (see Supported Leagues)
  • team / team1 / team2 - Team identifier (name, city, or abbreviation)
    • Athlete Sports (Tennis, MMA): Use athlete names (e.g., djokovic, serena-williams)
    • Doubles/Teams: Use + to combine multiple athletes (e.g., djokovic+federer)

Query Parameters

Parameter Type Default Description
aspect string 4-3 Aspect ratio: 4-3 (1440x1080), 16-9 (1920x1080), or 1-1 (1080x1080)
style integer 1 Visual style 1-4 (matchup only)
logo boolean true Include league logo (matchup only)
badge string - Add quality badge overlay: ALT, 4K, HD, FHD, or UHD (matchup only)
winner string - Winning team identifier - displays losing team in greyscale (matchup only)
fallback boolean false Single team: Return league thumb. Matchup: Use greyscale league logo for missing teams
title string - League Thumb: A title to display on the league thumb for sports that are not based on matchups (motorsports, etc.). Requires ALLOW_EVENT_OVERLAYS=true.
subtitle string - League Thumb: A subtitle to display on the league thumb for sports that are not based on matchups (motorsports, etc.). Requires ALLOW_EVENT_OVERLAYS=true.
iconurl string - League Thumb: Optional image URL to display on the league thumb for sports that are not based on matchups (motorsports, etc.). Must be an http:// or https:// URL with a public hostname; private and loopback targets are rejected unless ALLOW_INSECURE_OVERLAY_URLS=true. Requires ALLOW_EVENT_OVERLAYS=true.

Matchup Styles

Applies to: /:league/:team1/:team2/thumb only

Examples below include logo=true to display the league logo in the center.

Style Description Preview
1: Diagonal Split Diagonal split with team colors separated by a white line. Style 1
2: Gradient Blend Smooth gradient blend between team colors. Style 2
3: Minimalist Badge (Light) Minimalist design with team circles, VS text, and light background. Style 3
4: Minimalist Badge (Dark) Minimalist design with team circles, VS text, and dark background. Style 4
5: Grid Background Dark background with grey diagonal grid lines and fade to black effect. Style 5
6: Grid with Team Colors Dark background with team color gradient grid lines and fade to black effect. Style 6
98: 3D Embossed with League Logo 3D embossed design with textured backgrounds, reflections, metallic VS badge, and league logo at top.
Credit: @oOStroudyOo		 Style 98
99: 3D Embossed 3D embossed design with textured backgrounds, reflections, and metallic VS badge.
Credit: @shelf on Dispatcharr Discord		 Style 99

Examples

League Thumbnails

Dark gradient background with centered league logo.

League Preview URL
NHL NHL Thumb /nhl/thumb
NBA NBA Thumb /nba/thumb
MLB MLB Thumb /mlb/thumb
MLS (1:1) MLS Thumb /mls/thumb?aspect=1-1

Team Thumbnails

Team color gradient background with centered team logo.

Team Preview URL
Leafs Leafs Thumb /nhl/leafs/thumb
Raptors Raptors Thumb /nba/raptors/thumb
Blue Jays Blue Jays Thumb /mlb/bluejays/thumb

Matchup Thumbnails

Basic:

GET /nhl/leafs/canadiens/thumb
GET /nba/raptors/lakers/thumb?style=2
GET /mlb/bluejays/yankees/thumb?logo=false
GET /nhl/oilers/flames/thumb?style=99
GET /mls/toronto-fc/lafc/thumb?badge=4K
GET /nhl/canucks/bruins/thumb?badge=HD&style=3
GET /nhl/jets/blackhawks/thumb?style=5
GET /nhl/senators/rangers/thumb?style=6

Fallback Behavior

When fallback=true is set, the API gracefully handles missing data instead of returning errors.

Unsupported League Fallback

If a league is not configured but exists in ESPN’s API, automatically uses ESPN provider.

Request Behavior
/eng.w.1/team1/team2/thumb?fallback=true Detects unconfigured league → creates temporary config → resolves teams normally

This enables support for 100+ ESPN leagues (e.g., WSL, Brazilian Serie A, J-League, Liga MX lower divisions) without manual configuration.

Single Team Fallback

If a team is not found, returns the league thumbnail instead.

Request Preview Behavior
/nba/invalidteam/thumb?fallback=true Single Team Fallback Returns NBA league thumbnail

Matchup Fallback

If one or both teams are not found, uses greyscale league logo for missing teams.

Request Preview Behavior
/nhl/leafs/invalidteam/thumb?fallback=true&logo=true Matchup Fallback Valid team + greyscale NHL logo
/nba/invalidteam1/invalidteam2/thumb?fallback=true&logo=true Both Teams Fallback Both sides use greyscale NBA logo

Winner Effect

The winner parameter displays the losing team in greyscale (35% opacity with grey colors), making the winner stand out in full color.

Team Matching: Uses the same flexible matching as team parameters - accepts team names, cities, or abbreviations.

Basic Usage:

GET /nhl/leafs/canadiens/thumb?winner=leafs
GET /nba/lakers/celtics/thumb?winner=lakers&style=2
GET /mlb/yankees/redsox/thumb?winner=yankees&logo=true
Request Preview Result
/nhl/leafs/canadiens/thumb?winner=leafs Winner Leafs Leafs in color, Canadiens greyscale
/nhl/leafs/canadiens/thumb?winner=canadiens&style=2 Winner Canadiens Canadiens in color, Leafs greyscale

Combined with Other Parameters:

GET /nfl/chiefs/49ers/thumb?winner=chiefs&badge=4K
GET /nba/warriors/cavaliers/thumb?winner=warriors&style=99

Flexible Team Matching:

GET /nhl/leafs/canadiens/thumb?winner=toronto      # City name
GET /nba/lakers/celtics/thumb?winner=lal           # Abbreviation
GET /mlb/yankees/redsox/thumb?winner=new-york      # Partial match

If the winner doesn’t match either team, both teams display in full color (no error returned).

Athlete Sports (Singles) 

GET /tennis/djokovic/federer/thumb
GET /tennis/serena-williams/osaka/thumb?style=2
GET /ufc/jon-jones/stipe-miocic/thumb

Tennis Doubles 

GET /tennis/djokovic+federer/nadal+murray/thumb
GET /tennis/serena-williams+venus-williams/osaka+azarenka/thumb?style=3
GET /tennis/ram+salisbury/koolhof+skupski/thumb?logo=false

Output

  • Default: 1440x1080 PNG (4:3 aspect ratio)
  • 16:9: 1920x1080 PNG
  • 1:1 (Square): 1080x1080 PNG

Notes

  • League: Dark gradient with league logo centered
  • Team: Team color gradient with team logo centered
  • Matchup: Split design with team colors and logos
  • Automatically selects best logo variants based on contrast

Deprecated Endpoint

  • /:league/leaguethumb → Use /:league/thumb