This page documents the routes that actually exist in the codebase. The big correction versus the old inline docs is simple: tmdbKey is always required for the renderer, while mdblistKey is optional there but required by proxy config validation.
Main public surface exposed by the app.
| Method | Path | Purpose | Notes |
|---|---|---|---|
GET | /{type}/{id}.jpg | Stateless poster/backdrop/logo/thumbnail rendering. | Main image API. Logos still use a .jpg path but return PNG. |
GET | /api/version | Returns currentVersion, githubPackageVersion, and repoUrl. | Useful for self-hosted version checks. |
GET | /api/proxy-manifest?url=... | Inspects a source manifest and returns normalized catalog descriptors. | Used by the configurator. |
GET | /proxy/manifest.json?url=...&tmdbKey=...&mdblistKey=... | Query-config proxy manifest. | Fast test path with CORS enabled. |
GET | /proxy/{config}/manifest.json | Path-config proxy manifest. | Preferred stable production form. |
GET | /proxy/{config}/{resource...} | Forwards addon traffic and rewrites artwork to ERDB URLs. | Catalog/meta JSON are rewritten; other resources pass through. |
Canonical route: GET /{type}/{id}.jpg
| Field | Values | Default | Notes |
|---|---|---|---|
tmdbKey | TMDB v3 API key | required | Hard requirement. Alias: tmdb_key. |
mdblistKey | MDBList API key | optional | Needed for MDBList ratings unless the server already has MDBLIST_API_KEY(S). Alias: mdblist_key. |
simklClientId | SIMKL client_id | optional | Only for direct SIMKL ratings. Alias: simkl_client_id. |
ratings | tmdb, mdblist, imdb, tomatoes, tomatoesaudience, letterboxd, metacritic, metacriticuser, trakt, simkl, rogerebert, myanimelist, anilist, kitsu | all providers | Global provider fallback. Empty string disables ratings. |
type | poster, backdrop, logo, thumbnail | - | thumbnail is episode-only. |
lang | TMDB language code | en | Examples: en, it, es-ES, pt-BR. |
ratingStyle | glass, square, plain | glass, except logo -> plain | Alias: style. |
imageText | original, clean, alternative | original, except backdrop -> clean | Alias: posterText. |
posterRatingsLayout | top, bottom, left, right, top-bottom, left-right | top-bottom | Vertical poster layouts can use posterRatingsMaxPerSide and posterVerticalBadgeContent. |
backdropRatingsLayout | center, right-vertical | center | Backdrop-only layout. |
thumbnailRatingsLayout | center, center-top, center-bottom, center-vertical, center-top-vertical, center-bottom-vertical, left, left-top, left-bottom, left-vertical, left-top-vertical, left-bottom-vertical, right, right-top, right-bottom, right-vertical, right-top-vertical, right-bottom-vertical | center | Thumbnail-only layout. |
thumbnailSize | small, medium, large | medium | Thumbnails only support tmdb and imdb ratings. |
| ID format | Kind | Behavior |
|---|---|---|
tt0133093 | IMDb title | Movie or series lookup. |
tt0944947:1:1 | IMDb episode | Series IMDb ID plus season and episode. |
tmdb:603 | TMDB inferred | Works, but tmdb:movie:603 or tmdb:tv:1399 is preferred. |
tmdb:tv:1399:1:1 | TMDB episode | Explicit TV episode lookup. |
tvdb:121361:1:1 | TVDB aired-order episode | Useful for bridged episode numbering. |
realimdb:tt0944947:1:1 | IMDb TV bridge | Use this when the addon really sources series or episode metadata from IMDb IDs and you want ERDB to keep that IMDb-oriented TV resolution. |
kitsu:1 | Kitsu anime | Anime-native mapping flow. |
anilist:16498 / mal:5114 / anidb:69 | Anime-native IDs | Enable anime-only provider paths. |
thumbnailRatings falls back to thumbnailRatings -> backdropRatings -> ratings.
posterStreamBadges and backdropStreamBadges fall back to streamBadges.
posterQualityBadgesStyle and backdropQualityBadgesStyle fall back to qualityBadgesStyle.
verticalBadgeContent is accepted as a generic fallback for the type-specific vertical badge params.
Poster/backdrop/thumbnail negotiate WebP vs JPEG via Accept; logos always return image/png.
GET /poster/tmdb:movie:603.jpg?tmdbKey=YOUR_TMDB_KEY&ratings=tmdb,imdb&posterRatingsLayout=top-bottom&ratingStyle=glass
GET /thumbnail/tt0944947:1:1.jpg?tmdbKey=YOUR_TMDB_KEY&thumbnailRatings=tmdb,imdb&thumbnailRatingsLayout=center-bottom&thumbnailSize=largeProxy config can live in query parameters for testing or inside a base64url JSON path segment for production.
| Field | Required | Notes |
|---|---|---|
url | yes | Absolute source manifest URL. |
tmdbKey | yes | Required by proxy config validation. |
mdblistKey | yes | Required by proxy config validation even if renderer-only requests can omit it. |
posterEnabled / backdropEnabled / logoEnabled / thumbnailEnabled | no | False keeps original artwork for that type. |
translateMeta | no | Localizes metadata through TMDB when lang is available. |
ratings, per-type ratings, styles, layouts, badge settings | no | Same semantics as the image renderer. |
seriesMetadataProvider / aiometadataProvider | no | Controls TV ID normalization for tricky addon flows, especially addons that actually expose IMDb-based series metadata and should therefore use realimdb-style resolution. |
catalogNames / hiddenCatalogs / searchDisabledCatalogs / discoverOnlyCatalogs | no | Catalog customization maps and arrays. |
erdbBase | no | Overrides the absolute ERDB base used in generated artwork URLs. |
GET /proxy/manifest.json?url=https://addon.example.com/manifest.json&tmdbKey=YOUR_TMDB_KEY&mdblistKey=YOUR_MDBLIST_KEY
GET /proxy/{base64url(jsonConfig)}/manifest.json
GET /proxy/{base64url(jsonConfig)}/catalog/movie/top.jsonUseful integration details that are easy to miss when wiring ERDB behind another proxy or CDN.
| Topic | Behavior |
|---|---|
/api/version | Returns currentVersion, githubPackageVersion, and repoUrl. |
/api/proxy-manifest | Returns normalized catalog descriptors including key, extraKeys, supportsSearch, searchRequired, and discoverOnly. |
Vary: Accept | Important for caching poster/backdrop/thumbnail responses. |
X-ERDB-Cache | Image responses expose hit, miss, or shared. |
Server-Timing | Image responses expose auth, tmdb, mdb, stream, render, and total timing phases. |
Proxy CORS | Proxy routes and /proxy/manifest.json send Access-Control-Allow-Origin: * and support OPTIONS. |