Integrations

This page is the user-facing walkthrough for connecting Sublarr to the rest of your stack. The settings reference for these connections lives at Settings → Connections — this page is the guide you follow first.

Sonarr / Radarr

The most common setup. Sonarr/Radarr sources truth — what’s in the library, what got imported, what got upgraded. Sublarr subscribes to that stream.

Connection

In Sublarr → Settings → Connections → Sonarr (or Radarr) → Add instance:

Field	Where to find it in Sonarr/Radarr
URL	The base URL you use to access the *arr UI. Example: http://sonarr:8989.
API key	Sonarr → Settings → General → API Key.
Label	Free text — used in dropdowns when you have multiple instances.

Click Test — green = connected. Sublarr will start importing your library on the first scheduled sync; trigger immediate import via Trigger sync in the row.

Multiple instances

You can register as many Sonarr / Radarr instances as you have. Sublarr deduplicates by media ID across them. Common patterns:

Pattern	Setup
Anime + Western split	Two Sonarrs (one anime, one western). Two rows in Sublarr.
4K + 1080p split	Two Radarrs (one per resolution). Same.
Sonarr-A + Sonarr-B-test	Production + staging. Disable the staging row in Sublarr until ready to go live.

Inbound webhooks (for fast import)

Without webhooks, Sublarr polls Sonarr/Radarr on its scheduled interval. With webhooks, the *arr pushes import events to Sublarr immediately, so a search for the new episode starts within seconds rather than waiting for the next poll cycle.

Set up in the *arr UI:

1. Sonarr/Radarr → Settings → Connect → + → Webhook.
2. Name: Sublarr.
3. On Grab + On Import + On Upgrade.
4. URL: copy from Sublarr → Settings → Connections → Webhooks → Sonarr URL.
5. Method: POST.
6. Headers: add X-Api-Key: <your-Sublarr-API-key> — the same key as under Settings → General → Security. This is the only header the inbound endpoint accepts; X-Webhook-Secret belongs to outgoing webhooks and is ignored here, so a request carrying it is rejected with 401 Unauthorized.
7. Save.

After that, Sublarr’s manual_action_required event fires only on legitimate exceptions — most imports flow silently end-to-end.

Path Mapping

If Sonarr/Radarr’s view of paths differs from Sublarr’s view, configure path mapping. See Path Mapping for the full reference. The wizard offers this in step 4 of the onboarding wizard.

Media servers

Media servers are added under Settings → Connections → Media Servers → Add Server. Each row has a Name, the fields of its type, a Path Mapping, an Enabled toggle and Test Connection. The field reference is on Settings → Connections.

Plex

Plex needs a scan after Sublarr writes a subtitle, otherwise the new track won’t appear in the player.

Field	Where to find it in Plex
Server URL	http://<plex-host>:32400
X-Plex-Token	Plex Settings → Troubleshooting → View XML; the URL carries X-Plex-Token=.... The Plex docs walk through this in detail.

Test Connection reports the server name and version. After a subtitle is written, Sublarr asks Plex for a partial scan of the episode’s or film’s folder in the library that contains it. Only when no Plex library contains that folder are the libraries of the matching type — TV for an episode, movies for a film — scanned in full. A full scan on every subtitle almost always means the path mapping does not match Plex’s view of the files.

Jellyfin and Emby

Both use the same server type, Jellyfin / Emby:

Field	Where to find it
Server URL	http://<host>:8096
API Key	Jellyfin: Dashboard → API Keys → Create. Emby: Server → API Keys.
Server Type	jellyfin (default) or emby.

No user ID is needed. Sublarr looks the item up by its path and refreshes only that item; when no item has that path, the whole library is refreshed.

Kodi

Field	Where to find it
Server URL	The Kodi web interface, http://<kodi-host>:8080. Enable Allow remote control via HTTP in Kodi’s settings.
Username / Password	Only if HTTP Basic Auth is enabled in Kodi’s web server settings.

Shoko

Shoko is more than a refresh target: with a Shoko server connected, Sublarr takes the exact AniDB anime, episode id and absolute episode number of each file from Shoko instead of resolving them from titles. Some providers search only by those ids — the catalog source TsukiHime finds no episodes without Shoko.

Field	Where to find it
Server URL	http://<shoko-host>:8111
API Key	A persistent Shoko API key. Leave blank to use Username / Password instead.

After a subtitle is written, Sublarr asks Shoko to rescan that file; a file Shoko does not know triggers a scan of the import folders.

Media server path mapping

If a media server sees the files under a different path than Sublarr, fill its Path Mapping with from:to pairs (Sublarr’s path, then the server’s), separated by ; when there are several: /media/tv:/data/tv;/media/movies:/data/films. The longest matching pair wins, and pairs match whole folders only. This is separate from the Sonarr/Radarr Path Mapping above. Details: Settings → Connections → Media server path mapping.

Standalone (no *arr)

When you don’t run Sonarr/Radarr or want Sublarr to manage a folder outside their control:

1. Settings → Connections → Standalone → Add folder.
2. Path: absolute path inside Sublarr’s container, and inside its media folder (e.g. /media/anime). Since 1.18.0 a folder outside the media folder is refused: mount it in the container under /media/… and add that path.
3. Label: sidebar display name.
4. Scan interval: optional per-folder override; default uses the global cadence.

Standalone folders coexist with *arr instances. Files found there that aren’t in *arr show up in Library tagged “standalone”. Since 1.18.0 standalone titles have their own ids, so their settings never mix with a Sonarr series or Radarr movie of the same number. Removing a watched folder also removes its titles from the library (files on disk stay untouched).

Tip

Mix-and-match is supported: Sonarr-managed series for current shows, Standalone folders for archive content the *arr stack doesn’t know about. Sublarr handles both transparently.

Outbound integrations

For systems Sublarr should push to (e.g. custom CMS, in-house pipeline, alerting):

Mechanism	Use for
Notification channels	Generic event delivery via Apprise — Discord, Slack, Telegram, email, custom JSON. See Notifications.
Outbound hooks	Direct HTTP POST per event. See Hooks & Webhooks.

Health summary

Once everything’s connected, Settings → Diagnostics shows aggregate health across all integrations in one view — *arr instances reachable, media servers online, providers healthy, translation backends responsive.