Frequently Asked Questions

General Questions

Account & API
How do I get an API key?
▼

You can get a free API key by:

  1. Visiting the registration page
  2. Creating an account with your email and username
  3. Accessing your dashboard to view your API key

Free tier includes 10,000 requests per month. Upgrade to Premium or Pro for more features and higher limits.

What are the differences between API tiers (Free, Pro, Premium)?
▼

TOP Posters offers three tiers to suit different needs:

  • Free: 10,000 requests/month, basic rating sources (IMDb, Metacritic, RT), English posters only.
  • Pro: 30,000+ requests/month, 25+ rating sources, full style customization, all 35+ languages, trend indicators, and technical specs banners.
  • Premium: All Pro features plus Episode Thumbnails with ratings for TV shows.

You can compare all features and upgrade your plan on the pricing page.

Support
Where can I get help if I have more questions?
▼

We're here to help! You can reach us through:

Stremio Support

Setup & Installation
How do I configure posters in Stremio?
▼
⭐ Recommended — TOP Posters Addon Wrapper
The easiest and most complete way to use TOP Posters in Stremio is through the TOP Posters Addon Wrapper. It acts as a single proxy that wraps all your existing Stremio addons — automatically applying poster and thumbnail overlays without requiring any per-addon configuration. Catalog order, custom names and enable/disable controls are all managed from your dashboard.

→ Set up the Addon Wrapper in your dashboard

How it works:

  1. Go to the Addon Wrapper tab in your dashboard
  2. Import your existing Stremio addons by pasting their manifest URLs
  3. Install the generated personal wrapper URL in Stremio (one click)
  4. All catalogs from your imported addons will now display posters and thumbnails with rating badges, based on your API tier

Alternative — direct integration via compatible addons
If you prefer not to use the Wrapper, you can configure your API key directly in any compatible Stremio addon (e.g. AIOMetadata). Open the addon configuration page, enter your TOP Posters API key in the designated field, save and install. Note that this approach only covers the specific addon and does not provide full API support across all your catalogs. You can find a list of compatible addons on the homepage.

How do I configure episode thumbnails in Stremio?
▼
⭐ Recommended — use the Addon Wrapper
With the TOP Posters Addon Wrapper, episode thumbnails work automatically — no addon ordering required. The wrapper proxies metadata from your imported addons and injects the thumbnail overlays in a single step. Episode thumbnails require a Premium tier API key.

→ Configure thumbnail settings in your dashboard

Alternative — manual addon order configuration

If you are using a compatible addon directly (without the Wrapper), episode thumbnails require a specific addon order in Stremio:

Understanding Addon Order
Stremio processes addons in order, and the first addon in your list has priority. If multiple addons provide metadata for the same content, Stremio uses the one that appears first in your list.
  1. Find a metadata addon that supports thumbnails (e.g., AIOMetadata)
  2. Configure it with your TOP Posters API key, save and install in Stremio
  3. In your addon list, move the metadata addon to the top (it must be first)
  4. Thumbnails will now be provided by that addon across all content in Stremio
Troubleshooting
Why aren't my episode thumbnails showing up?
▼

If episode thumbnails aren't appearing, check the following:

  1. API Tier: Episode thumbnails require a Premium plan. Check your tier on the API Key tab
  2. Thumbnails enabled: Make sure episode thumbnails are enabled in your Thumbnails tab
  3. Content Type: Thumbnails are only available for TV series, not movies
  4. Using the Wrapper? If yes, verify your addons are correctly imported in the Addon Wrapper
  5. Using a direct addon? Make sure it is positioned first in your Stremio addon list and the API key is entered correctly
I can see rating badges in thumbnails on desktop, but not on my device. Why?
▼

Different devices and clients have different UI layouts. The badge may be rendered behind Stremio's UI elements on some screens.

Solution: Configure the badge position per device from your dashboard:

  1. Go to the Thumbnails tab to set the default badge position
  2. For per-device overrides, use the User Agents tab — each device/client that has made a thumbnail request will appear here with its own position and size settings
  3. Try different positions (top-left, top-right, bottom-left, bottom-right) to find what works best on that device

The user agent settings let you fine-tune the badge for each device independently.

How do I manage catalog order and addon settings?
▼
⭐ Recommended — manage everything from your dashboard
With the TOP Posters Addon Wrapper, you control catalog order, enable/disable individual catalogs and rename them directly from the Addon Wrapper tab. No external tools needed, and changes are reflected instantly in your personal Stremio manifest.

Alternative — external addon manager
If you are managing addons directly in Stremio without the Wrapper, you can reorder them using stremio-addon-manager.vercel.app. Keep in mind that for full TOP Posters API support across all your addons, the Wrapper is strongly recommended.

Plex Support

Getting Started
Before you start — what you need to know
▼

TOP Posters integrates with Plex as a native Metadata Provider — a feature built into Plex Media Server that lets you connect external sources for artwork and metadata.

Once configured, TOP Posters becomes the primary metadata agent for your Movie and TV libraries. This means:

  • Your media posters and thumbnails will come from the TOP Posters API and will display multi-source rating badges from various platforms
  • The standard Plex agent fills in anything that's missing (title, synopsis, genres, cast...)
You must use the Plex Media Server web interface — not app.plex.tv
Metadata Agent settings are only available when you access Plex directly on the machine running the server. Open a browser on that machine and go to: http://localhost:32400/web

If your server is on another machine on your network, use its local IP address instead: http://[server-ip]:32400/web

These settings do not appear in the remote Plex web app (app.plex.tv) or in the Plex desktop/mobile clients.
Your API key is embedded in the URL
Unlike other integrations, with Plex you don't enter your API key in a settings panel. Instead, your key is embedded directly in the URL you paste into Plex — so each user gets a unique URL. You'll find your personal URL in the steps below. Get your key from your dashboard.
Installation
Step 1 — Install the Movies provider
▼

First, copy your personal Movies provider URL. Replace {YOUR_API_KEY} with the API key shown in your dashboard:

https://api.top-posters.com/{YOUR_API_KEY}/plex/movie
1 Add the Metadata Provider
  1. Open http://localhost:32400/web (or your server's local IP) in a browser
  2. Go to Settings (top-right gear icon)
  3. In the left sidebar, under Settings, click Metadata Agents
  4. In the Metadata Providers section, click + Add Provider
  5. Paste your Movies URL (from above) and click Save
2 Create a Metadata Agent
  1. On the same page, scroll down to the Metadata Agents section and click + Add Agent
  2. Set the Title to TOP Posters Movies
  3. Set the Primary Provider to TOP Posters Movies
  4. Click + to add Plex Movie as an Additional Provider (this fills in anything we don't provide)
  5. Click Save
Don't skip step 4
If you don't add Plex Movie as an Additional Provider, your library will show posters but no metadata (no plot, cast, ratings, etc.).
3 Apply to your Movie libraries
  1. In the left sidebar, under Manage, click Libraries
  2. Hover over a Movie library and click Edit Library
  3. Click the Advanced tab on the right side
  4. Change the Metadata Agent to TOP Posters Movies (if you don't see it, refresh the page)
  5. Click Save Changes
  6. Repeat for any other Movie libraries
Step 2 — Install the TV Shows provider
▼

The process for TV Shows is identical. Copy your personal TV provider URL:

https://api.top-posters.com/{YOUR_API_KEY}/plex/tv
1 Add the Metadata Provider
  1. Open http://localhost:32400/web (same as before)
  2. Go to Settings → Metadata Agents
  3. In Metadata Providers, click + Add Provider
  4. Paste your TV URL (from above) and click Save
2 Create a Metadata Agent
  1. In the Metadata Agents section, click + Add Agent
  2. Set the Title to TOP Posters TV Shows
  3. Set the Primary Provider to TOP Posters TV Shows
  4. Click + to add Plex Series as an Additional Provider
  5. Click Save
Don't skip step 4
If you don't add Plex Series as an Additional Provider, your library will show posters but no metadata (no plot, cast, ratings, etc.).
3 Apply to your TV libraries
  1. Go to Settings → Libraries
  2. Hover over a TV Shows library and click Edit Library
  3. Click the Advanced tab
  4. Change the Metadata Agent to TOP Posters TV Shows
  5. Click Save Changes
  6. Repeat for any other TV libraries
Step 3 — Refresh Metadata
▼

Now that the providers are configured, you need to refresh metadata so Plex fetches the new posters.

You're all set!
After refreshing, your library posters will display rating badges from TOP Posters. Badge style and language can be customised at any time from your dashboard.

To refresh an entire library:

  1. Go to Settings → Libraries
  2. Hover over a library, click the three dots (⋯) icon
  3. Select Refresh All Metadata

To refresh a single item:

  1. Open any movie or TV show page in Plex Web
  2. Click the three dots (⋯) button (next to Play)
  3. Select Refresh Metadata
Refreshing a large library takes time
Plex refreshes items in the background. For large libraries, it may take several minutes before all posters are updated. New posters appear as the refresh progresses — you don't need to wait for the entire library to finish.
Troubleshooting
Troubleshooting — I don't see TOP Posters in the agent list
▼

If the agent you created doesn't appear in the library's Advanced settings dropdown:

  • Refresh the page — Plex sometimes needs a browser refresh to show newly created agents
  • Check the provider URL — Go back to Settings → Metadata Agents → Metadata Providers and verify the URL was saved correctly. Make sure your API key is in the URL and has no typos
  • Verify your API key — Check that your key is active on your dashboard
  • Check the library type — The Movies agent only appears for Movie libraries, and the TV Shows agent only appears for TV Show libraries. Make sure you're editing the correct library type
Troubleshooting — Posters are not updating after refresh
▼

If posters haven't changed after a metadata refresh, try the following:

  • Force a full refresh: Open a movie page → three dots → Fix Incorrect Match, search for the title, and confirm the match. This forces Plex to fetch fresh metadata from your provider
  • Check Plex logs: In Plex Web, go to Settings → Troubleshooting → Download Logs and look for any errors related to your provider URL
  • Test the URL manually: Open your provider URL directly in a browser (e.g. https://api.top-posters.com/{YOUR_API_KEY}/plex/movie). You should see a JSON response with a MediaProvider object. If you get an error, your API key may be invalid or expired
  • Plex poster lock: If you manually set a poster for an item before, Plex may have locked it. Open the item → three dots → View Info → Poster tab → select the TOP Posters poster
Configuration
Can I customise badge styles, languages, and other features?
▼

Yes — all customisation for both Posters and Episode Thumbnails happens directly in your User Dashboard. Changes are applied instantly to the API and will appear on your media player after a metadata refresh.

The available options depend on your API Tier:

  • Badge Customisation — Choose visual styles and positions (Pro/Premium).
  • Languages — Get localized artwork in 35+ languages (Pro/Premium).
  • Rating Sources — Select which sources to display from 25+ available (Pro/Premium).
  • Technical Specs — Add banners for 4K, HDR, etc. (Pro/Premium).
  • Episode Thumbnails — Full configuration for TV show thumbnails (Premium).

Free tier users get the default style with IMDb, Metacritic, and Rotten Tomatoes in English.

How do Technical Specs badges work in Plex?
▼

In Plex, Technical Specs badges (showing resolution, audio format and HDR standard) work differently from Stremio. Instead of fetching specs from an external database, they are read directly from your media filenames.

This means that for a poster to show a specs badge, your file must include the relevant information in its name, following common naming conventions. For example:

  • Movie.Title.2160p.DV.TrueHD.Atmos.mkv → 4K · Dolby Vision · Dolby Atmos
  • Movie.Title.1080p.HDR10.DTS-HD.mkv → 1080p · HDR10 · DTS-HD MA
  • Movie.Title.2160p.SDR.AAC.mkv → 4K · AAC

The following tags are recognised in filenames:

  • Resolution: 2160p, 4K, UHD, 1080p, 720p
  • HDR: DV, DoVi, HDR10+, HDR10, HDR, HLG
  • Audio: TrueHD.Atmos, Atmos, DTS-X, DTS-HD.MA, DTS-HD, DTS, DD+, EAC3, AC3, AAC, FLAC

If none of these tags are found in the filename, no specs badge will be shown on that poster — even if the Technical Specs option is enabled in your dashboard.

Why are trend indicators not showing in Plex?
▼

Trend indicators (arrows showing if a movie is trending up or down) are a feature that highlights currently popular titles based on external lists.

Unlike Stremio, Plex does not use a list-based system for its library view. Since Plex is focused on your local media files rather than live-updating lists, it cannot correctly interpret the popularity metadata needed to display these indicators. Therefore, trend indicators are not available for Plex, even if enabled in your dashboard.

Other Platforms Support

Will you add support for other media players?
▼

We're actively working on integrations for more platforms. Currently supported:

  • Stremio — via compatible addons (see the Stremio section above)
  • Plex — via the native Metadata Provider (see the Plex section above)
  • Jellyfin — via the official TOP Posters plugin

If you'd like to request support for a specific platform, reach out via email or our Discord community.