API Reference
Shanty exposes a REST API at /api/* and a Subsonic-compatible API at /rest/*. All REST endpoints require authentication via session cookie unless noted otherwise.
Authentication
All /api/* endpoints (except the auth endpoints listed below) require an active session. To authenticate, call the login endpoint and include the returned session cookie in subsequent requests.
Endpoints
| Method |
Path |
Auth |
Description |
| GET |
/api/auth/setup-required |
No |
Check if initial setup is needed (returns {"required": true} if no users exist) |
| POST |
/api/auth/setup |
No |
Create the first admin user. Only works when no users exist. Body: {"username": "...", "password": "..."} |
| POST |
/api/auth/login |
No |
Log in. Body: {"username": "...", "password": "..."}. Returns user info and sets session cookie. |
| POST |
/api/auth/logout |
Yes |
Log out and clear session. |
| GET |
/api/auth/me |
Yes |
Get current user info (id, username, role). |
| GET |
/api/auth/users |
Admin |
List all users. |
| POST |
/api/auth/users |
Admin |
Create a new user. Body: {"username": "...", "password": "..."} |
| DELETE |
/api/auth/users/{id} |
Admin |
Delete a user. Cannot delete yourself. |
| PUT |
/api/auth/subsonic-password |
Yes |
Set Subsonic password for current user. Body: {"password": "..."} |
| GET |
/api/auth/subsonic-password-status |
Yes |
Check if current user has a Subsonic password set. |
Artists
| Method |
Path |
Auth |
Description |
| GET |
/api/artists |
Yes |
List all artists in the library. Supports ?limit=50&offset=0 pagination. Returns artist names, MBIDs, monitored status, and track counts (watched/owned/total). |
| POST |
/api/artists |
Yes |
Add (watch) an artist. Body: {"name": "...", "mbid": "..."}. At least one of name or mbid is required. Expands the artist's full discography into individual track wanted_items. |
| GET |
/api/artists/{id} |
Yes |
Get artist by local database ID. Returns artist info and local albums. |
| GET |
/api/artists/{id}/full |
Yes |
Get full artist detail with MusicBrainz enrichment. Accepts local ID or MBID. Returns discography with per-album status (owned/partial/wanted/unwatched), artist photo, bio, and banner. Supports ?quick=true to skip per-album track fetches. |
| DELETE |
/api/artists/{id} |
Admin |
Delete an artist from the library. |
| POST |
/api/artists/{id}/monitor |
Yes |
Enable monitoring for an artist. |
| DELETE |
/api/artists/{id}/monitor |
Yes |
Disable monitoring for an artist. |
Albums
| Method |
Path |
Auth |
Description |
| GET |
/api/albums |
Yes |
List all local albums. Supports ?limit=50&offset=0. |
| POST |
/api/albums |
Yes |
Add (watch) an album. Body: {"artist": "...", "album": "...", "mbid": "..."}. Accepts release or release-group MBID. Expands to individual track wanted_items. |
| GET |
/api/albums/{mbid} |
Yes |
Get album track listing by MBID (release or release-group). Returns tracks with per-track status. |
Tracks
| Method |
Path |
Auth |
Description |
| GET |
/api/tracks |
Yes |
List tracks. Supports ?limit=50&offset=0 and ?q=search for text search. |
| GET |
/api/tracks/{id} |
Yes |
Get a single track by local database ID. |
Search
Search queries MusicBrainz (either the local database or the remote API).
| Method |
Path |
Auth |
Parameters |
Description |
| GET |
/api/search/artist |
Yes |
q (required), limit (default 25) |
Search for artists by name. Returns MBID, name, disambiguation. |
| GET |
/api/search/album |
Yes |
q (required), artist (optional), limit (default 25) |
Search for albums. |
| GET |
/api/search/track |
Yes |
q (required), artist (optional), limit (default 25) |
Search for tracks. |
| GET |
/api/search/discography/{mbid} |
Yes |
(none) |
Get an artist's full discography (release groups) by MBID. |
Downloads
| Method |
Path |
Auth |
Description |
| GET |
/api/downloads/queue |
Yes |
List download queue. Optional ?status=pending|downloading|completed|failed|cancelled. |
| POST |
/api/downloads |
Yes |
Enqueue a manual download. Body: {"query": "..."}. |
| POST |
/api/downloads/sync |
Yes |
Sync wanted items to download queue. Returns count of found/enqueued/skipped. |
| POST |
/api/downloads/process |
Yes |
Start processing the download queue (background task). Returns a task_id. |
| POST |
/api/downloads/retry/{id} |
Yes |
Requeue a failed download. |
| DELETE |
/api/downloads/{id} |
Yes |
Cancel a download. |
Playlists
| Method |
Path |
Auth |
Description |
| POST |
/api/playlists/generate |
Yes |
Generate a playlist (preview, not saved). Body includes strategy, seed_artists, count, etc. |
| GET |
/api/playlists |
Yes |
List saved playlists for the current user. |
| POST |
/api/playlists |
Yes |
Save a playlist. Body: {"name": "...", "description": "...", "track_ids": [1, 2, 3]} |
| GET |
/api/playlists/{id} |
Yes |
Get a playlist with its tracks. |
| PUT |
/api/playlists/{id} |
Yes |
Update playlist name/description. Body: {"name": "...", "description": "..."} |
| DELETE |
/api/playlists/{id} |
Yes |
Delete a playlist. |
| GET |
/api/playlists/{id}/m3u |
Yes |
Export playlist as M3U file download. |
| POST |
/api/playlists/{id}/tracks |
Yes |
Add a track. Body: {"track_id": 123} |
| PUT |
/api/playlists/{id}/tracks |
Yes |
Reorder tracks. Body: {"track_ids": [3, 1, 2]} |
| DELETE |
/api/playlists/{id}/tracks/{track_id} |
Yes |
Remove a track from the playlist. |
Playlist Generation Body
Strategies: similar, genre, random, smart.
Ordering options: interleave, score, random.
Lyrics
| Method |
Path |
Auth |
Parameters |
Description |
| GET |
/api/lyrics |
Yes |
artist (required), title (required) |
Fetch lyrics from LRCLIB. Returns plain lyrics and time-synced lyrics if available. Cached for 30 days. |
System and Pipeline
| Method |
Path |
Auth |
Description |
| GET |
/api/status |
Yes |
Dashboard status: library summary, download queue, tagging queue, active tasks, scheduler info. |
| POST |
/api/pipeline |
Yes |
Trigger the full pipeline (sync + download + tag + organize). Returns task_ids. |
| POST |
/api/index |
Yes |
Trigger a library scan (background task). |
| POST |
/api/tag |
Yes |
Trigger tagging of untagged tracks (background task). |
| POST |
/api/organize |
Yes |
Trigger file organization (background task). |
| GET |
/api/tasks/{id} |
Yes |
Get task status (running/completed/failed, progress, message). |
Watchlist
| Method |
Path |
Auth |
Description |
| GET |
/api/watchlist |
Yes |
List wanted items for the current user. |
| DELETE |
/api/watchlist/{id} |
Yes |
Remove a wanted item. |
YouTube Authentication
| Method |
Path |
Auth |
Description |
| GET |
/api/ytauth/status |
Yes |
Get YouTube auth status: authenticated, cookie age, refresh status, yt-dlp version, API key status. |
| POST |
/api/ytauth/login-start |
Admin |
Launch Firefox + noVNC for interactive YouTube login. Returns VNC URL. |
| POST |
/api/ytauth/login-stop |
Admin |
Stop Firefox, export cookies, enable auto-refresh. |
| POST |
/api/ytauth/refresh |
Admin |
Trigger immediate headless cookie refresh. |
| DELETE |
/api/ytauth/cookies |
Admin |
Clear all cookies and Firefox profile, disable refresh. |
Monitor
| Method |
Path |
Auth |
Description |
| POST |
/api/monitor/check |
Admin |
Trigger an immediate check of all monitored artists for new releases. |
| GET |
/api/monitor/status |
Yes |
List all monitored artists with last check timestamps. |
Scheduler
| Method |
Path |
Auth |
Description |
| POST |
/api/scheduler/skip-pipeline |
Admin |
Skip the next scheduled pipeline run. |
| POST |
/api/scheduler/skip-monitor |
Admin |
Skip the next scheduled monitor check. |
MusicBrainz
| Method |
Path |
Auth |
Description |
| GET |
/api/mb-status |
Yes |
Check if local MusicBrainz database is available and get stats (artist/release/recording counts). |
| POST |
/api/mb-import |
Admin |
Trigger MusicBrainz database import (background task). Downloads dumps and imports. |
Config
| Method |
Path |
Auth |
Description |
| GET |
/api/config |
Yes |
Get current configuration. |
| PUT |
/api/config |
Admin |
Update configuration. Body is the full AppConfig JSON object. Writes to YAML file and updates in-memory config. |
Subsonic API
The Subsonic API is served at /rest/* and uses the Subsonic authentication protocol (username + MD5 token or plaintext password, passed as query parameters).
All Subsonic endpoints accept the standard Subsonic query parameters: u (username), p (password or enc: hex-encoded), t (MD5 token), s (salt), v (API version), c (client name), f (response format, defaults to XML).
Each endpoint is available at both /rest/endpoint and /rest/endpoint.view.
System
| Path |
Description |
/rest/ping |
Server health check. |
/rest/getLicense |
Returns license status (always valid). |
Browsing
| Path |
Description |
/rest/getMusicFolders |
List music library folders. |
/rest/getIndexes |
Get alphabetical artist index. |
/rest/getMusicDirectory |
Get contents of a directory (artist's albums or album's tracks). Parameter: id. |
/rest/getArtists |
Get all artists (ID3 tag based). |
/rest/getArtist |
Get an artist with albums. Parameter: id. |
/rest/getAlbum |
Get an album with tracks. Parameter: id. |
/rest/getSong |
Get a single track. Parameter: id. |
/rest/getGenres |
List all genres. |
Search
| Path |
Description |
/rest/search3 |
Search artists, albums, and tracks. Parameters: query, artistCount, albumCount, songCount, artistOffset, albumOffset, songOffset. |
Media
| Path |
Description |
/rest/stream |
Stream an audio file. Parameter: id. Transcodes Opus to MP3 if transcoding is enabled. |
/rest/download |
Download an audio file (original format). Parameter: id. |
/rest/getCoverArt |
Get cover art image. Parameter: id. |
Playlists
| Path |
Description |
/rest/getPlaylists |
List all playlists. |
/rest/getPlaylist |
Get a playlist with tracks. Parameter: id. |
/rest/createPlaylist |
Create or update a playlist. Parameters: name, songId (repeatable). |
/rest/deletePlaylist |
Delete a playlist. Parameter: id. |
Annotation
| Path |
Description |
/rest/scrobble |
Record a play. Parameters: id, submission (true/false). |
User
| Path |
Description |
/rest/getUser |
Get user details. Parameter: username. |
Connor Johnstone