Homepage dashboard

Homepage has no dedicated Sublarr widget, but its generic Custom API widget can read any JSON endpoint. Sublarr has a few read-only GET endpoints that return exactly the kind of summary numbers a dashboard tile needs.

Authentication

Homepage sends the key as a request header:

X-Api-Key: <your key>

Sublarr also accepts the key as an ?apikey= query parameter, but a header keeps it out of URLs and access logs.

Where the key comes from:

• Set it in the UI under Settings → System, in the API Keys section. That section is an advanced setting, so switch on Advanced Settings if it is hidden.
• Or set SUBLARR_API_KEY when you start the container, see Environment Variables.

If no API key is set and no UI password is enabled, the API accepts requests without any header. If you protect the UI with a password, you also need an API key — otherwise Homepage gets 401 Authentication required. A wrong key returns 401; repeated wrong keys from one IP address are temporarily blocked with 429.

/api/v1/health needs no key at all, which makes it a good first connectivity check.

Useful endpoints

All paths are relative to http://<HOST_IP>:5765.

Endpoint	Fields	Meaning
/api/v1/wanted/summary	by_status.wanted	Items still waiting for a subtitle. The key is missing while no item has that status.
	exhausted	Wanted items the search has given up on — see Wanted.
	upgradeable	Items marked as upgrade candidates.
/api/v1/history/stats	last_24h, last_7d	Subtitles downloaded in the last 24 hours and 7 days.
	total_downloads	All downloads ever recorded.
	by_provider	Download count per provider (an object; format: size counts the providers).
/api/v1/stats	downloads_today, total_subtitles	Downloads since midnight and the lifetime total.
/api/v1/health	status	healthy or unhealthy. No API key needed.

/api/v1/providers/health reports each provider separately as a list, so it has no single number to put in a tile. Use the Providers page for that.

Ready-to-paste services.yaml

This tile shows downloads at a glance. Replace <HOST_IP> and the key.

- Media:
    - Sublarr:
        icon: https://sublarr.de/favicon.png
        href: http://<HOST_IP>:5765
        description: Subtitle manager
        widget:
          type: customapi
          url: http://<HOST_IP>:5765/api/v1/history/stats
          refreshInterval: 60000 # optional, milliseconds
          headers:
            X-Api-Key: "{{HOMEPAGE_VAR_SUBLARR_API_KEY}}"
          mappings:
            - field: last_24h
              label: Last 24 h
              format: number
            - field: last_7d
              label: Last 7 days
              format: number
            - field: total_downloads
              label: Total
              format: number
            - field: by_provider
              label: Providers
              format: size

Each Custom API widget shows at most four fields in the default block view, which is why this tile stops at four.

{{HOMEPAGE_VAR_SUBLARR_API_KEY}} is Homepage’s environment substitution: set HOMEPAGE_VAR_SUBLARR_API_KEY on the Homepage container and the key stays out of services.yaml. Pasting the key directly works as well. Use an address Homepage itself can reach — if both run on a shared Docker network, http://sublarr:5765 works.

Add the wanted count

Wanted items come from a different endpoint, so they need a second widget. Switch widget: to a widgets: list; Homepage shows both blocks on the same tile:

        widgets:
          - type: customapi
            url: http://<HOST_IP>:5765/api/v1/wanted/summary
            headers:
              X-Api-Key: "{{HOMEPAGE_VAR_SUBLARR_API_KEY}}"
            mappings:
              - field: by_status.wanted
                label: Wanted
                format: number
              - field: exhausted
                label: Exhausted
                format: number
          - type: customapi
            url: http://<HOST_IP>:5765/api/v1/history/stats
            headers:
              X-Api-Key: "{{HOMEPAGE_VAR_SUBLARR_API_KEY}}"
            mappings:
              - field: last_24h
                label: Last 24 h
                format: number
              - field: total_downloads
                label: Total
                format: number

The icon

Homepage’s icon: also accepts a plain URL, which is what the snippets use. Once Sublarr is available in the Dashboard Icons collection you can switch to icon: sublarr.png. That file does not exist there yet, so until it does keep the URL.

Troubleshooting

• The tile shows an API error. Open the same URL with curl from the Homepage host: curl -H "X-Api-Key: <key>" http://<HOST_IP>:5765/api/v1/wanted/summary. 401 means a missing or wrong key, a connection error means Homepage cannot reach that address.
• A value stays empty. The field is missing in the response — for example by_status.wanted while nothing is wanted. Check the raw JSON with curl.