This page lists the routes for the current Aurral release. All paths start at
the Aurral origin.
GET and media routes read data. POST, PUT, PATCH, and DELETE routes
can change Aurral, Lidarr, files, users, or external services.
| Method |
Path |
Purpose |
GET |
/api/health/live |
Minimal liveness response |
GET |
/api/health/bootstrap |
Startup and authentication state |
GET |
/api/health |
Detailed application health |
GET |
/api/health/ws |
WebSocket connection statistics |
POST |
/api/health/stream-token |
Issue a short-lived token for media streams |
POST |
/api/auth/login |
Create a password-login session |
POST |
/api/auth/logout |
End a login session |
GET |
/api/auth/me |
Current authenticated identity |
GET |
/api/auth/api-key |
Read or create the instance API key |
POST |
/api/auth/api-key/rotate |
Replace the instance API key |
GET |
/api/auth/oidc/login |
Start an OpenID Connect login |
POST |
/api/auth/oidc/exchange |
Exchange an OpenID Connect code for a session |
The liveness, bootstrap, and health routes do not require authentication.
Aurral returns detailed health fields only for a request with a valid
credential. The image proxy is also public.
Before setup is complete, the onboarding routes are public. Lidarr feeds use a
token for each flow. Media and filesystem routes do their own authorization
checks. When you enable authentication, most other routes require an Aurral
credential.
| Protocol |
Path |
Purpose |
| WebSocket |
/ws |
Status, download, discovery, flow, and playlist updates |
The WebSocket accepts subscribe, unsubscribe, and ping JSON messages.
Subscriptions use the status, downloads, discovery, library,
weekly-flow, and playlists channels. The library channel sends a
library_scan_completed message after Aurral refreshes its canonical library.
For local password authentication, connect with the session token as
/ws?token=SESSION_TOKEN. Aurral also accepts reverse-proxy identity and LAN
auto-login for WebSocket connections. Aurral does not currently accept the
instance API key for WebSocket connections.
| Method |
Path |
Purpose |
POST |
/api/webhooks/lidarr |
Receive Lidarr import events for requested albums |
| Method |
Path |
Purpose |
GET |
/api/library/artists |
List library artists |
GET |
/api/library/artists/:mbid |
Get a library artist |
POST |
/api/library/artists |
Add an artist |
PUT |
/api/library/artists/:mbid |
Update artist monitoring |
DELETE |
/api/library/artists/:mbid |
Delete an artist |
POST |
/api/library/artists/:mbid/refresh |
Refresh an artist in Lidarr |
GET |
/api/library/albums?artistId=:id |
List an artist’s albums |
GET |
/api/library/albums/:id |
Get an album |
POST |
/api/library/albums |
Add an album |
POST |
/api/library/albums/request |
Request an album from search data |
PUT |
/api/library/albums/:id |
Update an album |
DELETE |
/api/library/albums/:id |
Delete an album |
GET |
/api/library/tracks |
List album tracks |
DELETE |
/api/library/tracks/:id |
Delete a library track file and prune canonical records when no media remains |
POST |
/api/library/refresh |
Queue a canonical library scan |
GET |
/api/library/refresh/:jobId |
Read canonical library scan status |
GET |
/api/library/canonical |
Read a bounded canonical page; provide a supported kind and pageSize (1-100) |
GET |
/api/library/favorites |
Read the current user’s library favorites |
POST |
/api/library/favorites |
Add or remove a library favorite; requires a user session |
GET |
/api/library/playback-queue |
Build a bounded playback queue page; optional page and pageSize (1-100) |
GET |
/api/library/stream/:songId |
Stream a library song |
GET |
/api/library/canonical-stream/:trackId |
Stream a canonical library track |
GET |
/api/library/file-stream/:albumId/:trackId |
Stream an album track file |
GET |
/api/library/rootfolder |
List Lidarr root-folder paths |
GET |
/api/library/lookup/:mbid |
Check whether an artist is in the library |
POST |
/api/library/lookup/batch |
Check multiple artists |
POST |
/api/library/albums/lookup/batch |
Check multiple albums |
GET |
/api/library/recent |
List 20 recently added artists |
GET |
/api/library/recent-releases |
List recent missing releases |
GET |
/api/library/downloads |
List download jobs |
GET |
/api/library/downloads/status |
Get statuses for the required albumIds query |
GET |
/api/library/downloads/status/all |
Get all download statuses |
POST |
/api/library/downloads/track |
Download or request a track |
POST |
/api/library/downloads/album |
Monitor an album and optionally run the configured search |
POST |
/api/library/downloads/album/search |
Trigger a Lidarr album search |
The artist and album add routes accept an optional managedBy value of
aurral or lidarr. If the value is absent, Aurral uses the user’s saved
library-owner preference and falls back to Lidarr when Lidarr is connected.
POST /api/library/downloads/track requires an authenticated user with the
addAlbum permission.
| Method |
Path |
Purpose |
GET |
/api/artists/:mbid |
Artist details and releases |
GET |
/api/artists/:mbid/overrides |
Get metadata-provider overrides |
PUT |
/api/artists/:mbid/overrides |
Set metadata-provider overrides |
GET |
/api/artists/:mbid/similar |
Similar artists |
GET |
/api/artists/:mbid/video |
Find a video for a named artist and track |
GET |
/api/artists/:mbid/cover |
Artist image metadata; refresh=true retries a stale link |
GET |
/api/artists/:mbid/preview |
Deezer top tracks and preview URLs |
GET |
/api/artists/:mbid/stream |
Stream progressive artist metadata with SSE |
POST |
/api/artists/:mbid/appears-on |
Find releases that include an artist |
POST |
/api/artists/release-groups/ratings |
Batch release ratings |
POST |
/api/artists/release-groups/covers |
Batch release covers |
GET |
/api/artists/release-group/:mbid |
Release-group details |
GET |
/api/artists/release-group/:mbid/cover |
Release-group cover metadata; refresh=true retries a stale link |
GET |
/api/artists/release-group/:mbid/tracks |
Release-group tracks |
GET /api/artists intentionally returns 404. Use /api/search or an artist
detail route instead.
| Method |
Path |
Purpose |
GET |
/api/search |
Search artists, albums, or tags |
GET |
/api/search/unified |
Unified search suggestions or results |
GET |
/api/requests |
List current artist and album requests |
DELETE |
/api/requests/:mbid |
Remove an artist request |
DELETE |
/api/requests/album/:albumId |
Remove an album request |
GET /api/search requires q. Its optional scope is artist (default),
album, or tag. The route also accepts limit and offset. Album searches
accept releaseTypes and sort. GET /api/requests accepts refresh=true.
| Method |
Path |
Purpose |
GET |
/api/discover |
Discovery sections |
GET |
/api/discover/related |
Related recommendations |
GET |
/api/discover/similar |
Cached discovery tags, genres, and seed artists |
GET |
/api/discover/filtered |
Filtered recommendations |
GET |
/api/discover/tags |
Discovery tags |
GET |
/api/discover/by-tag |
Recommendations for a tag |
GET |
/api/discover/nearby-shows |
Nearby events |
GET |
/api/discover/artwork/:presetId |
Discovery artwork |
GET |
/api/discover/playlists/:presetId/previews |
Deezer previews for an editorial playlist |
GET |
/api/discover/feedback |
Discovery feedback |
POST |
/api/discover/feedback |
Record discovery feedback |
DELETE |
/api/discover/feedback/:id |
Delete discovery feedback |
POST |
/api/discover/feedback/reset |
Reset discovery feedback |
GET |
/api/discover/preferences |
Discovery preferences |
POST |
/api/discover/preferences |
Update discovery preferences |
POST |
/api/discover/preferences/reset |
Reset discovery preferences |
POST |
/api/discover/playlists/adopt |
Create a flow from a discovery preset |
POST |
/api/discover/playlists/adopt-playlist |
Create a static playlist from a discovery preset |
POST |
/api/discover/refresh |
Refresh discovery data |
POST |
/api/discover/clear |
Clear artwork links, native-library image files, and metadata-provider caches |
POST |
/api/discover/clear-discovery |
Clear the discovery cache |
| Method |
Path |
Purpose |
GET |
/api/news |
Read recent news for the current user’s library |
GET |
/api/news/preferences |
Read the current user’s blocked publishers |
PATCH |
/api/news/preferences |
Replace the current user’s blocked publishers |
POST |
/api/news/feeds/disable |
Disable a news feed |
/api/news accepts an optional limit query parameter. News preferences are
user-scoped; the blockedPublishers request field is an array of publisher
names. The response includes refresh.checkedArtistCount,
refresh.queuedArtistCount, refresh.callsRemaining, and an optional
refresh.warning so clients can explain partial coverage and provider limits.
| Method |
Path |
Purpose |
GET |
/api/inbox |
Read the current user’s Inbox items and unread count |
POST |
/api/inbox/refresh |
Manually refresh the current user’s Inbox |
POST |
/api/inbox/read-all |
Mark the current user’s Inbox items as read |
PATCH |
/api/inbox/:id |
Read, save, unsave, dismiss, or add an Inbox item |
The canonical prefix is /api/playlists. The legacy /api/weekly-flow
prefix redirects to it with status 308.
| Method |
Path |
Purpose |
GET |
/api/playlists/status |
Flow worker and playlist status |
GET |
/api/playlists/jobs |
List flow jobs |
GET |
/api/playlists/jobs/:flowId |
List jobs for a flow or static playlist |
POST |
/api/playlists/research-missing |
Research all missing tracks in accessible operations |
POST |
/api/playlists/start/:flowId |
Run a flow |
POST |
/api/playlists/flows |
Create a flow |
PUT |
/api/playlists/flows/:flowId |
Update a flow |
DELETE |
/api/playlists/flows/:flowId |
Delete a flow |
PUT |
/api/playlists/flows/:flowId/enabled |
Enable or disable a flow |
POST |
/api/playlists/flows/:flowId/static-playlist |
Save completed flow tracks as a static playlist |
POST |
/api/playlists/flows/:flowId/tracks/:jobId/research |
Research a flow track again |
GET |
/api/playlists/flows/:flowId/lidarr-import-list |
Create or read the Lidarr feed token and item count |
GET |
/api/playlists/artwork/:playlistId |
Get playlist artwork |
PUT |
/api/playlists/artwork/:playlistId |
Upload playlist artwork |
DELETE |
/api/playlists/artwork/:playlistId |
Delete playlist artwork |
POST |
/api/playlists/artwork/:playlistId/generate |
Generate playlist artwork |
GET |
/api/playlists/stream/:jobId |
Stream a playlist track |
GET |
/api/playlists/staging-stream/:jobId |
Stream a staged track |
POST |
/api/playlists/shared-playlists |
Create a shared playlist |
POST |
/api/playlists/shared-playlists/import |
Import a shared playlist |
PUT |
/api/playlists/shared-playlists/:playlistId |
Update a shared playlist |
DELETE |
/api/playlists/shared-playlists/:playlistId |
Delete a shared playlist |
POST |
/api/playlists/shared-playlists/:playlistId/tracks |
Add a shared-playlist track |
DELETE |
/api/playlists/shared-playlists/:playlistId/tracks/:jobId |
Delete a shared-playlist track |
POST |
/api/playlists/shared-playlists/:playlistId/tracks/:jobId/research |
Research a shared-playlist track |
POST |
/api/playlists/shared-playlists/:playlistId/research-missing |
Research all missing tracks |
POST |
/api/playlists/quality-upgrades/:playlistId/:jobId |
Search for a track upgrade |
POST |
/api/playlists/quality-upgrades/:playlistId |
Search for playlist upgrades |
POST |
/api/playlists/quality-upgrades |
Search for upgrades in accessible operations |
POST |
/api/playlists/shared-playlists/:playlistId/sync |
Sync a shared playlist |
PUT |
/api/playlists/playlists/:playlistId/retry-cycle |
Pause or resume retries for a static playlist |
POST |
/api/playlists/jobs/:jobId/approve |
Approve a flow job |
POST |
/api/playlists/jobs/:jobId/deny |
Deny a flow job |
DELETE |
/api/playlists/jobs/completed |
Delete completed jobs |
DELETE |
/api/playlists/jobs/all |
Delete all jobs |
GET |
/api/playlists/worker/settings |
Get worker settings |
PUT |
/api/playlists/worker/settings |
Update worker settings |
POST |
/api/playlists/worker/start |
Start the worker |
POST |
/api/playlists/worker/stop |
Stop the worker |
POST |
/api/playlists/reset |
Reset selected flow playlists |
POST |
/api/playlists/playlist/:playlistType/create |
Ensure configured smart-playlist files exist |
The repeated playlists segment in
/api/playlists/playlists/:playlistId/retry-cycle is the current route.
| Method |
Path |
Purpose |
GET |
/api/playlists/import/spotify/status |
Spotify connection status |
POST |
/api/playlists/import/spotify/oauth/start |
Start Spotify OAuth |
POST |
/api/playlists/import/spotify/oauth/complete |
Complete Spotify OAuth |
DELETE |
/api/playlists/import/spotify |
Disconnect Spotify |
GET |
/api/playlists/import/spotify/playlists |
List Spotify playlists |
POST |
/api/playlists/import/spotify/preview |
Preview a Spotify import |
POST |
/api/playlists/import/spotify |
Import Spotify playlists |
| Method |
Path |
Purpose |
GET |
/api/playlists/import/listenbrainz/playlists |
List playlists for the linked ListenBrainz account |
POST |
/api/playlists/import/listenbrainz/preview |
Preview a ListenBrainz import |
POST |
/api/playlists/import/listenbrainz |
Import a ListenBrainz playlist |
| Method |
Path |
Purpose |
GET |
/api/playlists/import/lastfm/playlists |
List Last.fm Library, Mix, and Recommended stations |
POST |
/api/playlists/import/lastfm/preview |
Preview a Last.fm station import |
POST |
/api/playlists/import/lastfm |
Import a Last.fm station |
| Method |
Path |
Purpose |
GET |
/api/feeds/lidarr/flows/:flowId.json |
Token-authenticated Lidarr-compatible flow feed |
| Method |
Path |
Purpose |
GET |
/api/users |
List users |
POST |
/api/users |
Create a user |
PATCH |
/api/users/:id |
Update a user |
DELETE |
/api/users/:id |
Delete a user |
GET |
/api/users/me/listening-history |
Get listening-history settings for the current user |
GET |
/api/users/me/lidarr-preferences |
Current user’s Lidarr preferences |
PATCH |
/api/users/me/lidarr-preferences |
Update current user’s Lidarr preferences |
GET |
/api/users/me/discover-layout |
Current user’s discovery layout |
PATCH |
/api/users/me/discover-layout |
Update current user’s discovery layout |
POST |
/api/users/me/password |
Change current user’s password |
GET |
/api/users/me/plex-link/status |
Read the current user’s Plex link |
POST |
/api/users/me/plex-link/oauth/pin |
Start Plex linking for the current user |
POST |
/api/users/me/plex-link/oauth/complete |
Complete Plex linking for the current user |
DELETE |
/api/users/me/plex-link |
Remove the current user’s Plex link |
GET |
/api/users/plex-link/home-users |
List Plex home users |
POST |
/api/users/:id/plex-link/managed |
Link a managed Plex user |
DELETE |
/api/users/:id/plex-link |
Remove a managed Plex link |
The current-user Plex-link routes require authentication. The Plex home-user
and managed-link routes require administrator access.
Every route in this section requires an administrator.
| Method |
Path |
Purpose |
GET |
/api/settings |
Read settings |
POST |
/api/settings |
Update settings |
GET |
/api/settings/storage-health |
Run or return the storage health check |
GET |
/api/settings/tasks |
List scheduled maintenance tasks |
POST |
/api/settings/tasks/clear-stale |
Clear stale task runs |
GET |
/api/settings/lidarr/profiles |
List Lidarr quality profiles |
GET |
/api/settings/lidarr/metadata-profiles |
List Lidarr metadata profiles |
GET |
/api/settings/lidarr/root-folders |
List Lidarr root folders |
GET |
/api/settings/lidarr/tags |
List Lidarr tags |
GET |
/api/settings/lidarr/test-library-access |
Test Lidarr library access |
GET |
/api/settings/lidarr/test |
Test Lidarr configuration |
POST |
/api/settings/lidarr/apply-community-guide |
Apply recommended Lidarr settings |
POST |
/api/settings/slskd/test |
Test slskd |
POST |
/api/settings/prowlarr/test |
Test Prowlarr |
GET |
/api/settings/prowlarr/indexers |
List Prowlarr Usenet indexers |
POST |
/api/settings/nzbget/test |
Test NZBGet |
POST |
/api/settings/sabnzbd/test |
Test SABnzbd |
POST |
/api/settings/ytdlp/test |
Test yt-dlp |
GET |
/api/settings/download-clients |
Read download client settings metadata |
POST |
/api/settings/download-clients/:key/test |
Test a download client |
POST |
/api/settings/gotify/test |
Test Gotify |
POST |
/api/settings/plex/auth/pin |
Start Plex authentication |
POST |
/api/settings/plex/auth/check |
Check Plex authentication |
POST |
/api/settings/plex/resources |
List Plex resources |
POST |
/api/settings/plex/test |
Test Plex |
GET |
/api/settings/plex/libraries |
List Plex libraries |
GET |
/api/settings/plex/libraries/:sectionId/access-check |
Check access to a Plex library |
POST |
/api/settings/plex/sync |
Synchronize Plex |
POST |
/api/settings/navidrome/test |
Test Navidrome credentials |
GET |
/api/settings/playback |
Read playback settings |
POST |
/api/settings/playback/:key/test |
Test a playback integration |
The instance API key has no user identity. Account linking and local play-event
recording require a user’s login session.
| Method |
Path |
Purpose |
GET |
/api/scrobbling/status |
Read scrobbling provider status |
GET |
/api/scrobbling/lastfm/link |
Start or read Last.fm linking; requires a user session |
GET |
/api/scrobbling/lastfm/link/callback |
Complete Last.fm linking |
DELETE |
/api/scrobbling/lastfm/link |
Unlink Last.fm |
GET |
/api/scrobbling/listenbrainz/link |
Read ListenBrainz linking |
PUT |
/api/scrobbling/listenbrainz/link |
Link ListenBrainz; requires a user session |
DELETE |
/api/scrobbling/listenbrainz/link |
Unlink ListenBrainz |
PUT |
/api/scrobbling/koito/link |
Configure Koito; requires a user session |
DELETE |
/api/scrobbling/koito/link |
Unlink Koito |
GET |
/api/play-events |
Read local play history |
POST |
/api/play-events |
Record a local play event; requires a user session |
These routes accept requests only until onboarding is complete. During initial
setup, Aurral does not require a credential for these routes.
| Method |
Path |
Purpose |
POST |
/api/onboarding/lidarr/profiles |
List Lidarr quality profiles |
POST |
/api/onboarding/lidarr/metadata-profiles |
List Lidarr metadata profiles |
POST |
/api/onboarding/lidarr/test |
Test Lidarr credentials |
POST |
/api/onboarding/navidrome/test |
Test Navidrome credentials |
POST |
/api/onboarding/complete |
Complete onboarding |
| Method |
Path |
Purpose |
GET |
/api/filesystem/browse |
Browse server directories |
POST |
/api/filesystem/ensure |
Create or validate a server directory |
GET |
/api/image-proxy |
Resolve a legacy proxied image URL through the native image cache |
GET |
/api/image-proxy/:cacheKey |
Fetch a cached native-library image |
Image-proxy routes are public. Before onboarding, filesystem routes do not
require authentication. After onboarding, Aurral requires an administrator
credential for filesystem routes. Aurral accepts the instance API key. Do not
expose an Aurral server directly to the public internet. Some /api routes do
not require an API key.
| Method |
Path |
Purpose |
GET or POST |
/rest/:method.view |
Authenticated Subsonic API methods |
The Subsonic API supports XML and JSON responses. Use the account’s Subsonic
credentials or token authentication; the instance API key is not a Subsonic
credential. See Navidrome and Subsonic for the
supported client behavior.
