Cover Endpoint

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

Endpoints:

  • /:league/cover[.png] - League cover (dark gradient with logo)
  • /:league/:team/cover[.png] - Team cover (team color gradient with logo)
  • /:league/:team1/:team2/cover[.png] - Matchup cover (split design, 1080x1440)

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 3-4 Aspect ratio: 3-4 (1080x1440), 9-16 (1080x1920), 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 cover. Matchup: Use greyscale league logo for missing teams
title string - League Cover: An optional title to display on the league cover for sports that are not based on matchups (motorsports, etc.). Requires ALLOW_EVENT_OVERLAYS=true.
subtitle string - League Cover: An optional subtitle to display on the league cover for sports that are not based on matchups (motorsports, etc.). Requires ALLOW_EVENT_OVERLAYS=true.
iconurl string - League Cover: Optional image URL to display on the league cover 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/cover only

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

Style Description Preview
1: Horizontal Split Horizontal 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 Covers

Dark gradient background with centered league logo.

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

Team Covers

Team color gradient background with centered team logo.

Team Preview URL
Leafs Leafs Cover /nhl/leafs/cover
Raptors Raptors Cover /nba/raptors/cover
Blue Jays Blue Jays Cover /mlb/bluejays/cover

Matchup Covers

Basic:

GET /nhl/leafs/canadiens/cover
GET /nba/raptors/warriors/cover?style=2
GET /mlb/bluejays/orioles/cover?logo=false
GET /nhl/oilers/jets/cover?style=99
GET /mls/toronto-fc/montreal/cover?badge=UHD
GET /nhl/canucks/flames/cover?badge=4K&style=2
GET /nhl/senators/sabres/cover?style=5
GET /mls/vancouver/seattle/cover?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/cover?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 cover instead.

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

Matchup Fallback

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

Request Preview Behavior
/nhl/leafs/invalidteam/cover?fallback=true&logo=true Matchup Fallback Valid team + greyscale NHL logo
/mlb/invalidteam1/invalidteam2/cover?fallback=true&logo=true Both Teams Fallback Both sides use greyscale MLB 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/cover?winner=leafs
GET /nba/lakers/celtics/cover?winner=lakers&style=2
GET /mlb/yankees/redsox/cover?winner=yankees&logo=true
Request Preview Result
/nhl/leafs/canadiens/cover?winner=leafs Winner Leafs Leafs in color, Canadiens greyscale
/nhl/leafs/canadiens/cover?winner=canadiens&style=2 Winner Canadiens Canadiens in color, Leafs greyscale

Combined with Other Parameters:

GET /nfl/chiefs/49ers/cover?winner=chiefs&badge=UHD
GET /nba/warriors/cavaliers/cover?winner=warriors&style=99

Flexible Team Matching:

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

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

Athlete Sports 

GET /tennis/djokovic/federer/cover
GET /tennis/djokovic+federer/nadal+murray/cover?style=3
GET /ufc/jon-jones/stipe-miocic/cover?style=2

Output

  • Default: 1080x1440 PNG (3:4 aspect ratio)
  • 9:16: 1080x1920 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
  • Identical to thumbnail but in portrait orientation
  • Perfect for vertical/portrait displays and mobile screens

Deprecated Endpoint

  • /:league/leaguecover → Use /:league/cover