Endpoint reference

This page lists the routes for the current Aurral release. All paths start at the Aurral origin.

The app API contract defines stable request and response fields for official apps. Public GET /api/health/bootstrap reports the API version and implemented features. Read the API overview for authentication. An API key gives administrator access. Routes that change data are not read-only.

GET and media routes read data. POST, PUT, PATCH, and DELETE routes can change Aurral, files, users, or external services.

Health and authentication

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. Administrators only
POST	/api/auth/api-key/rotate	Replace the instance API key. Administrators only
POST	/api/auth/reauth	Confirm the current password with { "currentPassword": "…" } before a sensitive account change
GET	/api/auth/oidc/login	Start an OpenID Connect login
POST	/api/auth/oidc/exchange	Exchange an OpenID Connect code for a session
POST	/api/auth/oidc/link/start	Start linking single sign-on to the current user and return the authorization URL
GET	/api/auth/google/login	Start a Google sign-in
POST	/api/auth/google/exchange	Exchange a Google sign-in code for a session
GET	/api/auth/google/link	Start linking a Google account to the current user
POST	/api/auth/google/link/start	Start linking a Google account and return the authorization URL

The Google sign-in routes return 404 when that sign-in method is off. They sign in only users who already linked the account. The Google link routes, the password change, and the identity changes require a sign-in in the last 15 minutes. Otherwise, call /api/auth/reauth first. Google returns to /sso/google/callback, and OIDC returns to /sso/callback.

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 and Deezer preview links are 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.

Realtime updates

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, and playlists channels. The library channel sends a library_scan_completed message after Aurral refreshes the 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. The instance API key does not work for WebSocket connections.

Library

Method	Path	Purpose
GET	/api/library/artists	List library artists
GET	/api/library/artists/:mbid	Get a library artist
GET	/api/library/artists/:id/cover	Get a Library artist’s image, or the art of one of its albums
POST	/api/library/artists	Add an artist
GET	/api/library/artists/:mbid/monitoring	Get an artist’s monitoring
PUT	/api/library/artists/:mbid	Update artist monitoring
POST	/api/library/artists/:mbid/monitoring/preview	Plan an artist’s monitoring with { "monitoring": … } without saving it
GET	/api/library/monitoring/defaults	Read the default monitoring rules and how many artists use them
POST	/api/library/monitoring/defaults/preview	Count what new default rules would download with { "rules": … }. Admin only
PUT	/api/library/monitoring/defaults	Save the default monitoring rules with { "rules": … }. Admin only
POST	/api/library/lidarr-conversion/dismiss	Dismiss the report shown after Aurral 3 takes over a Library that Lidarr ran. { "monitorArtists": true } also starts default monitoring for those artists. Admin only
GET	/api/library/monitoring/exclusions?artistMbid=	List the albums and tracks deleted from monitoring, for one artist or all
DELETE	/api/library/monitoring/exclusions/:id	Let monitoring download an excluded album or track again
DELETE	/api/library/artists/:mbid?deleteFiles=true|false	Delete an artist. An artist without a MusicBrainz ID takes its Library id instead. deleteFiles=true also deletes its files in the Library folder
PUT	/api/library/artists/:id/mbid	Set a library artist’s MusicBrainz ID with { "mbid": "…" }, or clear it with { "mbid": null }
GET	/api/library/artists/:id/matches?q=	MusicBrainz artists a library artist could be, searched by q or its name
GET	/api/library/albums/:id/matches?q=	MusicBrainz release groups a library album could be: its artist’s releases when the artist has a MusicBrainz ID, otherwise a search by q or its title
PUT	/api/library/albums/:id/release-group	Set a library album’s MusicBrainz release group with { "mbid": "…" }, or clear it with { "mbid": null }. Returns 409 for an album whose files have MusicBrainz album tags
GET	/api/library/albums?artistId=:id	List an artist’s albums
GET	/api/library/albums/:id	Get an album
GET	/api/library/albums/:id/cover	Get an album’s Library artwork as an image. Art in the album’s files comes first
POST	/api/library/albums	Add an album
POST	/api/library/albums/request	Request an album from search data
PUT	/api/library/albums/:albumId	Monitor or stop monitoring an album and all of its tracks with { "monitored": true | false }
GET	/api/library/albums/:albumId/status	Get the download status of an album
POST	/api/library/albums/:albumId/cancel	Cancel queued and active downloads for an album
DELETE	/api/library/albums/:albumId?deleteFiles=true|false	Remove an album
GET	/api/library/tracks	List album tracks
DELETE	/api/library/tracks/:id	Delete a library track file and prune Library records when no media remains. Returns 409 when its only file is in a read-only folder
PUT	/api/library/tracks/:trackId	Monitor or stop monitoring a track with { "monitored": true | false }. Stopping cancels an upgrade in progress
POST	/api/library/refresh	Queue a library scan. mode is quick, the default, or full to read every file again
GET	/api/library/refresh	Read the ID and status of the scheduled library scan
GET	/api/library/refresh/:jobId	Read the status of a library scan
GET	/api/library/files	Read the latest ingest or clean up operation. Admin only
GET	/api/library/files/read-only-folders	List read-only folders with each one’s track count and whether Aurral can read it, and whether a library scan is running. Admin only
POST	/api/library/files/read-only-folders	Add a read-only folder with { "path": "…" } and scan it. Returns 400 when the folder is missing, unreadable, or overlaps the Library folder or another read-only folder
DELETE	/api/library/files/read-only-folders	Remove a read-only folder with { "path": "…" }. Its music leaves the Library and its files stay
POST	/api/library/files/ingest/check	Check an ingest folder with { "sourcePath": "…" }: music file count, whether Hardlink works, and any read-only folder it is in
POST	/api/library/files/ingest	Start an ingest with { "sourcePath": "…", "mode": "move" | "copy" | "hardlink", "monitor": "none" | "tracks" | "albums", "fillTags": true }. monitor defaults to none, and fillTags to false. Returns 409 while another operation runs
POST	/api/library/files/cleanup	Start renaming Library files in the Library folder to Aurral’s names and filling in their missing tags. Returns 409 while another operation runs
GET	/api/library/files/operations/:id	Read an operation’s status, progress, and counts
GET	/api/library/files/operations/:id/items	Read an operation’s files. Optional status, offset, and limit up to 200
POST	/api/library/files/operations/:id/cancel	Stop an ingest or clean up after the current file. Files already done stay done
POST	/api/library/files/operations/:id/dismiss	Clear a finished operation, so GET /api/library/files returns no operation until the next one starts
POST	/api/library/files/operations/:id/remove-sources	Remove the files a Move ingest kept because the Library has their track, or the duplicate copies a clean up found. Each is checked again first. Returns 400 for a Copy or Hardlink ingest and 409 while another operation runs
GET	/api/library	Read one page of Library items. Requires a supported kind, and pageSize from 1 to 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 one page of a playback queue. Optional page, and pageSize from 1 to 100
GET	/api/library/stream/:albumId/:trackId	Stream a Library track
GET	/api/library/file-stream/:albumId/:trackId	Stream an album track file
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 the 20 artists with the newest library files
GET	/api/library/recent-releases	List recent missing releases
GET	/api/library/downloads/status	Get the statuses for the Library album IDs in the required albumIds query
POST	/api/library/downloads/track	Download or request a track
POST	/api/library/downloads/tracks/:trackId/research	Search for a replacement of a library track. Send the albumId. Returns 409 when a search for the track is already running
POST	/api/library/downloads/tracks/:trackId/replacement-job	Get the download job to use for a manual replacement search of a library track. Send the albumId. Returns 409 when a search for the track is already running

The album and track routes take the Library album or track ID. Monitoring, cancelling, or removing an album that Aurral only plays from a read-only folder returns 409 with album_owner_conflict.

An album status is one of complete, downloading, queued, blocked, cancelled, failed, partial, or missing. It includes per-track counts and, when blocked, failed, or partial needs action, a recovery object with a code (download_source_missing, review_required, or source_failed) and a message. Album add and request responses include the same status as albumStatus.

PUT /api/library/artists/:mbid sets an artist’s monitoring. It adds the artist when needed, which requires the addArtist permission. Send { "monitoring": { "monitored": true, "useDefault": true } }, { "monitoring": { "monitored": true, "useDefault": false, "rules": … } }, or { "monitoring": { "monitored": false } }. Rules have these fields, and a missing field takes the factory default:

Field	Values	Default
catalog	none, all, since, or latest	all
sinceYear	The first year for since	null
latestCount	1 to 10 releases for latest	1
newReleases	true or false	true
types	One or more of album, ep, and single	["album", "ep"]
extraTypes	live, compilation, soundtrack, remix, demo, dj-mix, and mixtape/street	[]
edition	standard or expanded	standard
topTracks	0 to 50	0

Rules that take nothing, with catalog none, newReleases off, and no top tracks, return 400 with invalid_monitor_rules. A request without monitoring stops monitoring.

The monitoring read and update return monitored, useDefault, rules, and defaultRules. The update and the preview also return monitoring with releaseGroupIds and releases for the releases being queued, topTracks, skipped with a reason for each skipped release (complete, covered, excluded, unmonitored, or metadata_unavailable), and skippedTracks with a reason for each skipped top track (excluded, in_library, on_release, or queued). If artist metadata is unavailable, the route returns 503 with metadata_unavailable and keeps the previous monitoring. POST /api/library/artists accepts the same monitoring.

DELETE /api/library/albums/:albumId and DELETE /api/library/artists/:mbid cancel unfinished downloads first. They return 409 with download_cancellation_failed when a download client does not confirm the cancellation. Removing an album records an exclusion, so the artist’s monitoring leaves it out, and the response has excluded: true. Requesting the album, or deleting its exclusion, lets monitoring download it again. Deleting a track file records a track exclusion that keeps it out of the artist’s top tracks.

Cancelling an album stops pending and active downloads and keeps tracks that already finished. Requesting the album again retries cancelled and failed tracks. Without a configured download source, an album request saves the album and reports download_source_missing instead of queueing downloads. A complete Usenet, Tidarr, Soulseek, or deemix release can fill several track jobs with one download attempt. If only some files verify, the remaining tracks continue through per-track fallback.

POST /api/library/downloads/track requires an authenticated user with the addAlbum permission. When libraryTrackId or trackMbid names a track in an album, the request monitors that track, queues it with its album, and responds with monitored: true.

Artist metadata

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/image	Artist image: Library art, or a redirect; w picks a width
GET	/api/artists/:mbid/preview	Deezer top tracks and preview URLs
GET	/api/deezer/preview/:trackId.mp3	Redirect to a current Deezer preview for a track
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 returns 404. Use /api/search or an artist detail route instead.

Search and requests

Method	Path	Purpose
GET	/api/search	Search artists, albums, or tags
GET	/api/search/unified	Unified search suggestions or results
GET	/api/search/link	Find the MusicBrainz artist, album, and track for a streaming-service link
GET	/api/requests	List current artist and album requests

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/search/link requires an encoded url. It accepts album, track, and artist links from open.spotify.com, music.apple.com, music.youtube.com, tidal.com, deezer.com, song.link, and album.link. It returns:

{
  "kind": "track",
  "artist": { "name": "Daft Punk", "mbid": "056e4f3e-d505-4dad-8ec1-d04f521cbb56" },
  "album": { "title": "Discovery", "mbid": "48117b90-a16e-34ca-a514-19c702df1158" },
  "track": { "title": "One More Time", "mbid": null },
  "source": "appleMusic"
}

source is spotify, appleMusic, youtubeMusic, tidal, deezer, or songlink. A null ID means no MusicBrainz match. YouTube Music track links do not report an album, so their album is null. Aurral reads names from each service’s public pages or lookup API. Spotify album and track links go through song.link. Other links return 400. A link the service cannot find returns 404, and an unreachable service returns 502. Aurral caches each link’s names for a day.

GET /api/requests accepts refresh=true to rebuild the list. Items include libraryAlbumId and requestGroupId when they’re known, and album downloads include albumGrab.libraryAlbumId.

Discovery

Method	Path	Purpose
GET	/api/discover	Discovery sections, with the current user’s recommendations
GET	/api/discover/status	Whether the current user’s discovery is refreshing, the current step, the last update time, and the last failure
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/editorial	Deezer editorial playlists: matches for the user’s top genres and tags, and playlists grouped by genre
GET	/api/discover/editorial/:playlistId	A Deezer editorial playlist with track previews
GET	/api/discover/editorial/links	Find the MusicBrainz artist and album for a Deezer track
POST	/api/discover/editorial/:playlistId/library	Add a Deezer editorial playlist to your library as a synced 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/blocked-tags	Genres the current user blocked
POST	/api/discover/blocked-tags	Block a genre with { tag }. Rejects tags that are not genres
DELETE	/api/discover/blocked-tags	Unblock the genre in the tag query parameter
GET	/api/discover/spotify-import	The current user’s imported Spotify history summary, or null
PUT	/api/discover/spotify-import	Replace the current user’s imported Spotify history with { artists } totals
DELETE	/api/discover/spotify-import	Remove the current user’s imported Spotify history
GET	/api/discover/preferences	Discovery preferences
POST	/api/discover/preferences	Update discovery preferences
POST	/api/discover/preferences/reset	Reset discovery preferences
POST	/api/discover/refresh	Refresh discovery data
POST	/api/discover/clear	Clear artwork links, cached image files, Library artwork copies, and metadata-provider caches
POST	/api/discover/clear-discovery	Clear the discovery cache

News

Method	Path	Purpose
GET	/api/news	Read recent news for the current user’s library
POST	/api/news/feeds/disable	Disable a news feed for everyone (admin only)

/api/news accepts optional mode, limit, and offset query parameters. mode=matched (the default) returns only stories that mention a library or recommended artist. mode=top returns every recent story. Each article lists the matched artists in artists. The response includes refresh.warning when no feed could be refreshed.

Inbox

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

Shared links

Method	Path	Purpose
GET	/api/share-links	List the current user’s live listen links
GET	/api/share-links/availability	Count the Library tracks a track, album, or artist would share
POST	/api/share-links	Create a listen link with an expiry and an optional download permission
DELETE	/api/share-links/:id	Stop file access, or stop a playlist link

Playlists and flows

The prefix is /api/playlists.

The routes call a static playlist a shared playlist.

Method	Path	Purpose
GET	/api/playlists/status	Download worker, flow, and static playlist status
GET	/api/playlists/jobs	List Library and accessible flow and playlist jobs
GET	/api/playlists/jobs/:playlistId	List jobs for a flow or static playlist
POST	/api/playlists/jobs/cancel	Cancel every pending or downloading song you can control
POST	/api/playlists/jobs/:jobId/cancel	Cancel a pending or downloading song without changing its monitoring
POST	/api/playlists/research-missing	Re-search every missing track in Wanted
GET	/api/playlists/jobs/:jobId/manual-search/sources	List the download clients available for a manual search
POST	/api/playlists/jobs/:jobId/manual-search	Search one download client for a track. Send sourceId, and mode set to missing or replacement
POST	/api/playlists/jobs/:jobId/manual-search/select	Queue one result from a manual search
POST	/api/playlists/start/:flowId	Run a flow
GET	/api/playlists/flow-templates	List flow templates
POST	/api/playlists/flows	Create a flow, optionally from a template with templateId
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/static-playlists	Create a static playlist
PUT	/api/playlists/static-playlists/:playlistId	Update a static playlist
PUT	/api/playlists/static-playlists/:playlistId/record-history	Enable or disable listening history for a static playlist
PUT	/api/playlists/static-playlists/:playlistId/track-availability	Show or hide track availability for a static playlist, with { "enabled": true | false }
DELETE	/api/playlists/static-playlists/:playlistId	Delete a static playlist
POST	/api/playlists/static-playlists/:playlistId/tracks	Add a static playlist track
DELETE	/api/playlists/static-playlists/:playlistId/tracks/:jobId	Delete a static playlist track
POST	/api/playlists/static-playlists/:playlistId/tracks/:jobId/research	Research a static playlist track
POST	/api/playlists/quality-upgrades/:playlistId/:jobId	Search for a track upgrade
POST	/api/playlists/quality-upgrades	Search for upgrades for every cutoff-unmet track in Wanted
POST	/api/playlists/static-playlists/:playlistId/sync	Sync a static playlist
POST	/api/playlists/jobs/:jobId/approve	Approve a download held for review
POST	/api/playlists/jobs/:jobId/deny	Deny a download held for review
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	Queue a rewrite of every flow and static playlist file

Cancelling a song needs accessPlaylists and access to its playlist, or the user who requested the Library download. Other users get 403. The track stays monitored, and other songs in the same album download keep downloading. The response holds the job’s new status and cleanupFailed. When a download client can’t confirm cleanup, the job stays cancel_requested; cancel again once the client is back. A finished job returns 409.

Searching again for a cancelled song from an album returns 409. Request the album again to retry it. Other cancelled songs can be searched again.

Spotify import

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

ListenBrainz import

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

YouTube Music import

These routes retrieve public playlists anonymously. Preview accepts a supported playlist URL. Import accepts the validated playlist ID returned by preview, fetches the source again, and stores the source title returned by YouTube Music.

Method	Path	Purpose
POST	/api/playlists/import/youtube-music/preview	Preview a public YouTube or YouTube Music playlist
POST	/api/playlists/import/youtube-music	Import and optionally schedule synchronization for the playlist

Last.fm import

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

Lidarr feed

Method	Path	Purpose
GET	/api/feeds/lidarr/flows/:flowId.json	Token-authenticated Lidarr-compatible flow feed

Users

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 the current user’s Last.fm, ListenBrainz, and Koito history sources
PATCH	/api/users/me/listening-history	Set or clear any of the current user’s history sources
GET	/api/users/me/identities	List the sign-in identities linked to the current user
DELETE	/api/users/me/identities/:id	Remove a linked identity. Returns 400 with last_auth_method when it is the last way to sign in
GET	/api/users/me/discover-layout	Current user’s discovery layout
PATCH	/api/users/me/discover-layout	Update current user’s discovery layout
GET	/api/users/me/theme	Current user’s theme settings and saved themes, or null
PUT	/api/users/me/theme	Replace the current user’s theme settings. Returns 400 when the theme is invalid
POST	/api/users/me/password	Change current user’s password

Administration and settings

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	Return the result of the last storage health check. It does not run the checks
POST	/api/settings/storage-health/check	Run the storage health check again
GET	/api/settings/tasks	List scheduled maintenance tasks
POST	/api/settings/tasks/clear-stale	Clear stale task runs
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/webhook/test	Test one webhook configuration
GET	/api/settings/playlist-files	Read the playlist file folder and naming setting
PUT	/api/settings/playlist-files	Change the owner prefix in playlist file names
GET	/api/backup	Download a backup zip. Requires a password entered in the last 15 minutes
POST	/api/backup/restore	Restore a backup zip sent as the request body, then restart

Logs

Every route in this section requires an administrator, except POST /api/logs/client.

Method	Path	Purpose
GET	/api/logs	Log entries, newest first. Optional level (the lowest level), cat, q text, fp, req, job, hours, limit up to 1000, and before or after an entry id to page
GET	/api/logs/problems	Warnings and errors from the last hours (default 24), grouped by fingerprint with a count and the latest entry
GET	/api/logs/export	A text file of the last hours (default 24) at level and above (default info), with a header that names the version and enabled integrations
PUT	/api/logs/debug	Turn debug logging on or off with { "enabled": true }
POST	/api/logs/client	Report a browser error. Any signed-in user

Scrobbling and play events

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
GET	/api/history-servers	List the current user’s media server history imports
PUT	/api/history-servers/:provider	Connect Navidrome or Jellyfin. Admins only
POST	/api/history-servers/:provider/sync	Import new plays now
DELETE	/api/history-servers/:provider	Disconnect and remove the imported plays
GET	/api/plex	Whether the Plex server is connected
POST	/api/plex/sign-in	Start a Plex sign-in
POST	/api/plex/sign-in/:id	Finish a Plex sign-in. With serverUrl, admins only
PATCH	/api/plex	Turn sending playlists to Plex on or off. Admins only
DELETE	/api/plex	Disconnect the Plex server. Admins only

GET /api/play-events lists plays recorded in Aurral. Plays imported from a media server are not included.

Onboarding

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/complete	Complete onboarding

Files and images

Method	Path	Purpose
GET	/api/filesystem/browse	Browse server directories
POST	/api/filesystem/ensure	Create or validate a server directory
POST	/api/image-proxy	Cache a remote image and return its same-origin /api/image-proxy/:cacheKey URL
GET	/api/image-proxy/:cacheKey	Fetch a cached native-library image

Fetching a cached image is public. Caching a new image requires a signed-in user. 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.

Subsonic

Method	Path	Purpose
GET or POST	/rest/:method.view	Subsonic and OpenSubsonic API methods

The Subsonic API supports XML and JSON responses. Use the account’s Subsonic password or token authentication. The instance API key does not work for Subsonic. See Navidrome and Subsonic for the supported client behavior.