Proxy requests

URL shape

http(s)://MIDDLEWARR_HOST/proxy/{appSlug}/{upstreamPath}

For example:

http://localhost:9292/proxy/homepage/api/v3/movie

The slug identifies an app. The supplied proxy key selects that app’s target service. Middlewarr removes the proxy prefix and joins the remaining path to the configured upstream base URL.

If the service base URL includes /radarr, a proxied /api/v3/movie request is sent under /radarr/api/v3/movie. Clients should not add that upstream URL base a second time to the Middlewarr proxy URL.

Authentication

Send the proxy key as:

X-Api-Key: YOUR_PROXY_KEY

For clients that require it, Middlewarr also accepts the query parameter apikey. If both are present, the header takes precedence. Prefer the header when the client supports it, to keep the credential out of URLs.

The app and selected proxy must both be active. An upstream service’s original API key is not the client credential for the Middlewarr proxy.

Permission matching

The allowlist matches the HTTP method and upstream API path. A granted GET does not implicitly grant other methods such as HEAD. Parameterized routes match the paths represented by that route.

Query parameters and body fields do not create additional permission boundaries. See Endpoint permissions.

Forwarding behavior

For an allowed request, Middlewarr:

• Removes the apikey query parameter before forwarding upstream.
• Replaces X-Api-Key with the service’s stored API key.
• Sets the upstream Host to the service’s host.
• Preserves the originating client’s User-Agent and appends a Via entry identifying the Middlewarr hop, such as 1.1 middlewarr.

The upstream service receives the remaining path, query, and request body through the reverse proxy. HTTP proxy handling also applies, including removal of hop-by-hop headers. Do not assume every client header is forwarded unchanged.

Response codes

Code	Middlewarr behavior
401 Unauthorized	Unknown or unavailable app route; inactive app/no active proxies; missing key; or no matching active proxy key
403 Forbidden	Authenticated request whose path and method are not enabled
502 Bad Gateway	Failure to reach the upstream service at the transport level
Upstream response	An allowed request otherwise receives the upstream service’s response

An upstream service or a front reverse proxy can return these same status codes. Use Middlewarr’s logs and access warnings to locate the failure.

Other server routes

GET /health is an unauthenticated server health check. It does not test all configured upstreams or prove that a proxy’s permissions are correct.

Administration uses /api/auth/* and /api/admin/v1/*, with the administrator’s session cookie and origin checks for writes. Proxy keys do not authorize those routes. These docs focus on operating the dashboard and proxy; they do not define a stable administration SDK contract.