API On this page Everything you can do in the web interface can also be done over HTTP, which makes it
easy to automate Soulsolid with curl, scripts or other tools. The web interface and
the API use the same addresses : when a request comes from the web interface you get
a web page, and when it comes from anything else you get JSON .
# How many tracks are in the library?
curl http://localhost:3535/library/tracks/count
# {"key":"tracks_count","value":1234}
# Import the download folder
curl -X POST http://localhost:3535/import/directory -d "directoryPath=/app/downloads"
# {"job_id":"…"}
# Follow the job
curl http://localhost:3535/jobs/<job_id> Request bodies can be sent as form fields (-d "key=value") or as JSON.
Soulsolid has no authentication : anyone who can reach it can use the API. Don’t
expose it to the internet without a reverse proxy that adds a login.
Responses# Each route below returns one of these kinds of responses:
Response What you get Page A full web page. Open it in a browser. Data The data shown on that part of the page, as JSON. Value A single value: {"key":"…","value":…}. OK {"message":"…"} on success, or {"error":"…"} with an HTTP error status.Job 202 Accepted with {"job_id":"…"}. The work runs as a background job ; follow it with /jobs/:id.File The file itself (audio, image, playlist, database). Send Accept: application/json to get {"type":"…","url":"…"} instead. JSON Always JSON.
Dashboard# Method Route What it does Response GET /Dashboard Page GET /dashboardDashboard Page GET /analyzeAnalyze section Page GET /dashboard/quick-actionsQuick actions card Data GET /healthReturns OK while the server is running Text
Settings# Method Route What it does Response GET /settingsSettings page Page GET /config/formCurrent settings Data PUT /settingsSave settings OK PUT /config/importSave import options OK PUT /config/pathsSave path templates OK GET /configThe whole configuration JSON GET /config?fmt=yamlThe config.yaml file as text YAML GET /config/database/downloadDownload a backup of the library database File
Library# Method Route What it does Response GET /libraryLibrary page Page GET /library/tableLibrary table Data GET /library/searchSearch the library (see parameters below) Data GET /library/tracks/:trackId/overviewTrack overview Data GET /library/artists/countNumber of artists Value GET /library/albums/countNumber of albums Value GET /library/tracks/countNumber of tracks Value GET /library/storage/sizeLibrary size on disk, in bytes Value GET /library/artists/:idOne artist JSON GET /library/albums/:idOne album JSON GET /library/tracks/:idOne track JSON GET /library/treeFolder tree of the library (?folder=downloads for the download folder) Value GET /library/tracks/:id/lyricsA track’s lyrics Value DELETE /library/tracks/:trackIdDelete a track and its file OK DELETE /library/albums/:albumIdDelete an album and its files OK DELETE /library/artists/:artistIdDelete an artist and their files OK
Search parameters# Parameter Default Meaning queryText to search for in artists, albums and tracks page1Page number limit50Results per page genreOnly tracks with this genre has_acoustidtrue or false: only tracks with or without an AcoustIDlyrics_filterOnly tracks in a given lyrics state lyrics_textOnly tracks whose lyrics contain this text added_after, added_beforeOnly tracks added in this date range
Method Route What it does Response GET /tag/:trackIdTag editor for a track (?source=db to show the library’s tags instead of the file’s) Page POST /tag/:trackIdSave a track’s tags OK GET /tag/:trackId/metadataEnabled metadata providers Data GET /tag/:trackId/search/:providerSearch a provider for matches Data GET /tag/:trackId/select/:provider?index=NFill the tag editor with a search result Page GET /tag/:trackId/:providerFill the tag editor with a provider’s best match Page GET /tag/:trackId/artworkThe track’s cover art File GET /tag/:trackId/fingerprintFingerprint the track and look up its AcoustID OK GET /tag/:trackId/fingerprint/viewThe track’s stored fingerprint Value GET /analyze/metadataMetadata analysis page Page POST /analyze/acoustidStart an AcoustID analysis of the library Job
Importing# Method Route What it does Response GET /importImport page Page GET /import/directory/formImport form, with the default folder Data GET /import/directory/badgesCurrent import options Data POST /import/directoryImport a folder (directoryPath) Job GET /import/queue/itemsTracks in the review queue Data GET /import/queue/items/groupedQueue grouped by ?type=artist or ?type=album Data GET /import/queue/headerQueue summary Data GET /import/queue/countNumber of tracks in the queue Value GET /import/queue/:id/artworkCover art of a queued track File POST /import/queue/:id/:actionAct on a queued track: import, replace, cancel or delete OK POST /import/queue/group/:groupType/:groupKey/:actionAct on a whole artist or album group OK POST /import/queue/clearEmpty the queue OK POST /import/prune/download-pathDelete the audio files in the download folder and empty the queue OK POST /import/watcher/toggleStart or stop the download folder watcher (action=start or action=stop) OK GET /import/watcher/statusWhether the watcher is running Data GET /import/watcher/toggle-stateWhether the watcher is running Data
Jobs# Method Route What it does Response GET /jobsJobs page Page GET /jobs/allEvery job, with links to its progress and logs JSON GET /jobs/activeRunning and waiting jobs Data GET /jobs/listJobs, optionally only those of one type (?prefix=download_) Data GET /jobs/latestThe 5 most recent jobs Data GET /jobs/countNumber of jobs (?filter=active for running and waiting ones) Value POST /jobs/start/:typeStart a job of the given type , e.g. calculate_metrics Job POST /jobs/clear-finishedRemove finished jobs and their logs OK GET /jobs/:idOne job’s status, progress and message JSON GET /jobs/:id/progressOne job’s progress Data GET /jobs/:id/logsOne job’s log as plain text (?color=true for a colored page) Text POST /jobs/:id/cancelCancel a job Data
Downloading# Add ?downloader=<name> to choose which plugin to use. Without it, the
first configured plugin is used.
Method Route What it does Response GET /downloadsDownload page Page POST /downloads/searchSearch (query, type: album, track, artist or link, limit) Data POST /downloads/search/albumsSearch albums (query) Data POST /downloads/search/tracksSearch tracks (query) Data GET /downloads/album/:albumId/tracksAn album’s tracks Data GET /downloads/chart/tracksThe service’s top tracks Data GET /downloads/user/infoYour account on the service, and its status Data GET /downloads/capabilitiesWhat the plugin supports JSON POST /downloads/trackDownload a track (trackId) Job POST /downloads/albumDownload an album (albumId) Job POST /downloads/artistDownload an artist’s discography (artistId) Job POST /downloads/tracksDownload several tracks (trackIds, comma-separated) Job POST /downloads/playlistDownload a playlist (trackIds, playlistName) Job
Lyrics# Method Route What it does Response GET /analyze/lyricsLyrics analysis page Page POST /analyze/lyricsStart a lyrics analysis (provider, skip_existing_lyrics, override_no_queue) Job GET /tag/:trackId/lyricsEnabled lyrics providers Data GET /tag/:trackId/lyrics/text/:providerLook up a track’s lyrics with a provider JSON GET /library/tracks/:id/lyricsA track’s lyrics Value GET /lyrics/queue/itemsTracks in the lyrics queue Data GET /lyrics/queue/items/groupedQueue grouped by ?type=artist or ?type=album Data GET /lyrics/queue/headerQueue summary Data GET /lyrics/queue/countNumber of tracks in the queue Value GET /lyrics/queue/:id/new_lyricsThe new lyrics found for a queued track Value POST /lyrics/queue/:id/:actionAct on a queued track: override, keep_old, no_lyrics, skip OK POST /lyrics/queue/group/:groupType/:groupKey/:actionAct on a whole artist or album group OK POST /lyrics/queue/clearEmpty the queue OK
Playlists# Method Route What it does Response GET /playlistsPlaylists page Page GET /playlists/:idOne playlist and its tracks Data GET /playlists/create-modalNew playlist form Data GET /playlists/:type/:id/playlistsPlaylists you can add a track, album or artist to Data GET /playlists/:id/exportDownload the playlist as .m3u File POST /playlists/Create a playlist (name, description) OK PUT /playlists/:idRename or edit a playlist (name, description) OK DELETE /playlists/:idDelete a playlist OK POST /playlists/itemsAdd music (playlist_id, item_type: track, album or artist, item_id) OK DELETE /playlists/:playlistId/tracks/:trackIdRemove a track from a playlist OK
File paths (Reorganize)# Method Route What it does Response GET /analyze/filesFile paths page Page POST /analyze/reorganizeStart a reorganize (fat32_safe=true to also make paths FAT32-safe) Job
Merge# Method Route What it does Response GET /analyze/mergeMerge page Page
Finding and merging duplicates is only available from the web interface. See
Merge .
Metrics# Method Route What it does Response GET /metrics/overviewNumber of tracks, artists and albums Data GET /metrics/charts/genreTracks per genre Data GET /metrics/charts/yearTracks per release year Data GET /metrics/charts/formatTracks per audio format Data GET /metrics/charts/metadataPercentage of tracks with each tag Data
To recalculate the metrics, start a calculate_metrics job with
POST /jobs/start/calculate_metrics.
Streaming# Method Route What it does Response GET /stream?path=<url-encoded path>Play or download an audio file from the library or download folder File
