Subsonic API

The Subsonic API allows anyone to build their own programs using Subsonic as the media server, whether they're on the web, the desktop or on mobile devices. All the Subsonic apps are built using the Subsonic API.

Feel free to join the Subsonic App Developers group for discussions, suggestions and questions.

Introduction

The Subsonic API allows you to call methods that respond in REST style xml. Individual methods are detailed below.

Please note that all methods take the following parameters:

Parameter Required Default Comment
u Yes The username.
p Yes* The password, either in clear text or hex-encoded with a "enc:" prefix. Since 1.13.0 this should only be used for testing purposes.
t Yes* (Since 1.13.0) The authentication token computed as md5(password + salt). See below for details.
s Yes* (Since 1.13.0) A random string ("salt") used as input for computing the password hash. See below for details.
v Yes The protocol version implemented by the client, i.e., the version of the subsonic-rest-api.xsd schema used (see below).
c Yes A unique string identifying the client application.
f No xml Request data to be returned in this format. Supported values are "xml", "json" (since 1.4.0) and "jsonp" (since 1.6.0). If using jsonp, specify name of javascript callback function using a callback parameter.

*) Either p or both t and s must be specified.

Remember to URL encode the request parameters. All methods (except those that return binary data) returns XML documents conforming to the subsonic-rest-api.xsd schema. The XML documents are encoded with UTF-8.

Authentication

If your targeting API version 1.12.0 or earlier, authentication is performed by sending the password as clear text or hex-encoded. Examples:

http://your-server/rest/ping.view?u=joe&p=sesame&v=1.12.0&c=myapp
http://your-server/rest/ping.view?u=joe&p=enc:736573616d65&v=1.12.0&c=myapp

Starting with API version 1.13.0, the recommended authentication scheme is to send an authentication token, calculated as a one-way salted hash of the password.

This involves two steps:

  1. For each REST call, generate a random string called the salt. Send this as parameter s.
    2. Use a salt length of at least six characters.
  2. Calculate the authentication token as follows: token = md5(password + salt). The md5() function takes a string and returns the 32-byte ASCII hexadecimal representation of the MD5 hash, using lower case characters for the hex values. The '+' operator represents concatenation of the two strings. Treat the strings as UTF-8 encoded when calculating the hash. Send the result as parameter t.

For example: if the password is sesame and the random salt is c19b2d, then token = md5("sesamec19b2d") = 26719a1196d2a940705a59634eb18eab. The corresponding request URL then becomes:

http://your-server/rest/ping.view?u=joe&t=26719a1196d2a940705a59634eb18eab&s=c19b2d&v=1.12.0&c=myapp

Error handling

If a method fails it will return an error code and message in an <error> element. In addition, the status attribute of the <subsonic-response> root element will be set to failed instead of ok. For example:

<?xml version="1.0" encoding="UTF-8"?>
<subsonic-response xmlns="http://subsonic.org/restapi" status="failed" version="1.1.0">
   <error code="40" message="Wrong username or password"/>
</subsonic-response>

The following error codes are defined:

Code Description
0 A generic error.
10 Required parameter is missing.
20 Incompatible Subsonic REST protocol version. Client must upgrade.
30 Incompatible Subsonic REST protocol version. Server must upgrade.
40 Wrong username or password.
41 Token authentication not supported for LDAP users.
50 User is not authorized for the given operation.
60 The trial period for the Subsonic server is over. Please upgrade to Subsonic Premium. Visit subsonic.org for details.
70 The requested data was not found.

Versions

This table shows the REST API version implemented in different Subsonic versions:

Subsonic version REST API version
6.1.4 1.16.1
6.1.2 1.16.0
6.1 1.15.0
6.0 1.14.0
5.3 1.13.0
5.2 1.12.0
5.1 1.11.0
4.9 1.10.2
4.8 1.9.0
4.7 1.8.0
4.6 1.7.0
4.5 1.6.0
4.4 1.5.0
4.2 1.4.0
4.1 1.3.0
4.0 1.2.0
3.9 1.1.1
3.8 1.1.0

Note that a Subsonic server is backward compatible with a REST client if and only if the major version is the same, and the minor version of the client is less than or equal to the server's. For example, if the server has REST API version 2.2, it supports client versions 2.0, 2.1 and 2.2, but not versions 1.x, 2.3+ or 3.x. The third part of the version number is not used to determine compatibility.

File structure vs ID3 tags

Starting with version 1.8.0, the API provides methods for accessing the media collection organized according to ID3 tags, rather than file structure.

For instance, browsing through the collection using ID3 tags should use the getArtists, getArtist and getAlbum methods. To browse using file structure you would use getIndexes and getMusicDirectory.

Correspondingly, there are two sets of methods for searching, starring and album lists. Refer to the method documentation for details.

API method documentation

System ping getLicense
Browsing getMusicFolders getIndexes getMusicDirectory getGenres getArtists getArtist getAlbum getSong getVideos getVideoInfo getArtistInfo getArtistInfo2 getAlbumInfo getAlbumInfo2 getSimilarSongs getSimilarSongs2 getTopSongs
Album/song lists getAlbumList getAlbumList2 getRandomSongs getSongsByGenre getNowPlaying getStarred getStarred2
Searching search search2 search3
Playlists getPlaylists getPlaylist createPlaylist updatePlaylist deletePlaylist
Media retrieval stream download hls getCaptions getCoverArt getLyrics getAvatar
Media annotation star unstar setRating scrobble
Sharing getShares createShare updateShare deleteShare
Podcast getPodcasts getNewestPodcasts refreshPodcasts createPodcastChannel deletePodcastChannel deletePodcastEpisode downloadPodcastEpisode
Jukebox jukeboxControl
Internet radio getInternetRadioStations createInternetRadioStation updateInternetRadioStation deleteInternetRadioStation
Chat getChatMessages addChatMessage
User management getUser getUsers createUser updateUser deleteUser changePassword
Bookmarks getBookmarks createBookmark deleteBookmark getPlayQueue savePlayQueue
Media library scanning getScanStatus startScan

ping

http://your-server/rest/ping Since 1.0.0

Used to test connectivity with the server. Takes no extra parameters.

Returns an empty <subsonic-response> element on success. Example.

getLicense

http://your-server/rest/getLicense Since 1.0.0

Get details about the software license. Takes no extra parameters. Please note that access to the REST API requires that the server has a valid license (after a 30-day trial period). To get a license key you must upgrade to Subsonic Premium.

Returns a <subsonic-response> element with a nested <license> element on success. Example.

getMusicFolders

http://your-server/rest/getMusicFolders Since 1.0.0

Returns all configured top-level music folders. Takes no extra parameters.

Returns a <subsonic-response> element with a nested <musicFolders> element on success. Example.

getIndexes

http://your-server/rest/getIndexes Since 1.0.0

Returns an indexed structure of all artists.

Parameter Required Default Comment
musicFolderId No If specified, only return artists in the music folder with the given ID. See getMusicFolders.
ifModifiedSince No If specified, only return a result if the artist collection has changed since the given time (in milliseconds since 1 Jan 1970).

Returns a <subsonic-response> element with a nested <indexes> element on success. Example.

getMusicDirectory

http://your-server/rest/getMusicDirectory
Since 1.0.0

Returns a listing of all files in a music directory. Typically used to get list of albums for an artist, or list of songs for an album.

Parameter Required Default Comment
id Yes A string which uniquely identifies the music folder. Obtained by calls to getIndexes or getMusicDirectory.

Returns a <subsonic-response> element with a nested <directory> element on success. Example 1. Example 2.

getGenres

http://your-server/rest/getGenres Since 1.9.0

Returns all genres.

Returns a <subsonic-response> element with a nested <genres> element on success. Example.

getArtists

http://your-server/rest/getArtists Since 1.8.0

Similar to getIndexes, but organizes music according to ID3 tags.

Parameter Required Default Comment
musicFolderId No If specified, only return artists in the music folder with the given ID. See getMusicFolders.

Returns a <subsonic-response> element with a nested <artists> element on success. Example.

getArtist

http://your-server/rest/getArtist Since 1.8.0

Returns details for an artist, including a list of albums. This method organizes music according to ID3 tags.

Parameter Required Default Comment
id Yes The artist ID.

Returns a <subsonic-response> element with a nested <artist> element on success. Example.

getAlbum

http://your-server/rest/getAlbum
Since 1.8.0

Returns details for an album, including a list of songs. This method organizes music according to ID3 tags.

Parameter Required Default Comment
id Yes The album ID.

Returns a <subsonic-response> element with a nested <album> element on success. Example.

getSong

http://your-server/rest/getSong Since 1.8.0

Returns details for a song.

Parameter Required Default Comment
id Yes The song ID.

Returns a <subsonic-response> element with a nested <song> element on success. Example.

getVideos

http://your-server/rest/getVideos Since 1.8.0

Returns all video files.

Returns a <subsonic-response> element with a nested <videos> element on success. Example.

getVideoInfo

http://your-server/rest/getVideoInfo Since 1.14.0

Returns details for a video, including information about available audio tracks, subtitles (captions) and conversions.

Parameter Required Default Comment
id Yes The video ID.

Returns a <subsonic-response> element with a nested <videoInfo> element on success. Example.

getArtistInfo

http://your-server/rest/getArtistInfo Since 1.11.0

Returns artist info with biography, image URLs and similar artists, using data from last.fm.

Parameter Required Default Comment
id Yes The artist, album or song ID.
count No 20 Max number of similar artists to return.
includeNotPresent No false Whether to return artists that are not present in the media library.

Returns a <subsonic-response> element with a nested <artistInfo> element on success. Example.

getArtistInfo2

http://your-server/rest/getArtistInfo2 Since 1.11.0

Similar to getArtistInfo, but organizes music according to ID3 tags.

Parameter Required Default Comment
id Yes The artist ID.
count No 20 Max number of similar artists to return.
includeNotPresent No false Whether to return artists that are not present in the media library.

Returns a <subsonic-response> element with a nested <artistInfo2> element on success. Example.

getAlbumInfo

http://your-server/rest/getAlbumInfo Since 1.14.0

Returns album notes, image URLs etc, using data from last.fm.

Parameter Required Default Comment
id Yes The album or song ID.

Returns a <subsonic-response> element with a nested <albumInfo> element on success. Example.

getAlbumInfo2

http://your-server/rest/getAlbumInfo2 Since 1.14.0

Similar to getAlbumInfo, but organizes music according to ID3 tags.

Parameter Required Default Comment
id Yes The album ID.

Returns a <subsonic-response> element with a nested <albumInfo> element on success. Example.

getSimilarSongs

http://your-server/rest/getSimilarSongs Since 1.11.0

Returns a random collection of songs from the given artist and similar artists, using data from last.fm. Typically used for artist radio features.

Parameter Required Default Comment
id Yes The artist, album or song ID.
count No 50 Max number of songs to return.

Returns a <subsonic-response> element with a nested <similarSongs> element on success. Example.

getSimilarSongs2

http://your-server/rest/getSimilarSongs2 Since 1.11.0

Similar to getSimilarSongs, but organizes music according to ID3 tags.

Parameter Required Default Comment
id Yes The artist ID.
count No 50 Max number of songs to return.

Returns a <subsonic-response> element with a nested <similarSongs2> element on success. Example.

getTopSongs

http://your-server/rest/getTopSongs Since 1.13.0

Returns top songs for the given artist, using data from last.fm.

Parameter Required Default Comment
artist Yes The artist name.
count No 50 Max number of songs to return.

Returns a <subsonic-response> element with a nested <topSongs> element on success. Example.

getAlbumList

http://your-server/rest/getAlbumList Since 1.2.0

Returns a list of random, newest, highest rated etc. albums. Similar to the album lists on the home page of the Subsonic web interface.

Parameter Required Default Comment
type Yes The list type. Must be one of the following: random, newest, highest, frequent, recent. Since 1.8.0 you can also use alphabeticalByName or alphabeticalByArtist to page through all albums alphabetically, and starred to retrieve starred albums. Since 1.10.1 you can use byYear and byGenre to list albums in a given year range or genre.
size No 10 The number of albums to return. Max 500.
offset No 0 The list offset. Useful if you for example want to page through the list of newest albums.
fromYear Yes (if type is byYear) The first year in the range. If fromYear > toYear a reverse chronological list is returned.
toYear Yes (if type is byYear) The last year in the range.
genre Yes (if type is byGenre) The name of the genre, e.g., "Rock".
musicFolderId No (Since 1.11.0) Only return albums in the music folder with the given ID. See getMusicFolders.

Returns a <subsonic-response> element with a nested <albumList> element on success. Example.

getAlbumList2

http://your-server/rest/getAlbumList2 Since 1.8.0

Similar to getAlbumList, but organizes music according to ID3 tags.

Parameter Required Default Comment
type Yes The list type. Must be one of the following: random, newest, frequent, recent, starred, alphabeticalByName or alphabeticalByArtist. Since 1.10.1 you can use byYear and byGenre to list albums in a given year range or genre.
size No 10 The number of albums to return. Max 500.
offset No 0 The list offset. Useful if you for example want to page through the list of newest albums.
fromYear Yes (if type is byYear) The first year in the range. If fromYear > toYear a reverse chronological list is returned.
toYear Yes (if type is byYear) The last year in the range.
genre Yes (if type is byGenre) The name of the genre, e.g., "Rock".
musicFolderId No (Since 1.12.0) Only return albums in the music folder with the given ID. See getMusicFolders.

Returns a <subsonic-response> element with a nested <albumList2> element on success. Example.

getRandomSongs

http://your-server/rest/getRandomSongs Since 1.2.0

Returns random songs matching the given criteria.

Parameter Required Default Comment
size No 10 The maximum number of songs to return. Max 500.
genre No Only returns songs belonging to this genre.
fromYear No Only return songs published after or in this year.
toYear No Only return songs published before or in this year.
musicFolderId No Only return songs in the music folder with the given ID. See getMusicFolders.

Returns a <subsonic-response> element with a nested <randomSongs> element on success. Example.

getSongsByGenre

http://your-server/rest/getSongsByGenre Since 1.9.0

Returns songs in a given genre.

Parameter Required Default Comment
genre Yes The genre, as returned by getGenres.
count No 10 The maximum number of songs to return. Max 500.
offset No 0 The offset. Useful if you want to page through the songs in a genre.
musicFolderId No (Since 1.12.0) Only return albums in the music folder with the given ID. See getMusicFolders.

Returns a <subsonic-response> element with a nested <songsByGenre> element on success. Example.

getNowPlaying

http://your-server/rest/getNowPlaying Since 1.0.0

Returns what is currently being played by all users. Takes no extra parameters.

Returns a <subsonic-response> element with a nested <nowPlaying> element on success. Example.

getStarred

http://your-server/rest/getStarred Since 1.8.0

Returns starred songs, albums and artists.

Parameter Required Default Comment
musicFolderId No (Since 1.12.0) Only return results from the music folder with the given ID. See getMusicFolders.

Returns a <subsonic-response> element with a nested <starred> element on success. Example.

getStarred2

http://your-server/rest/getStarred2 Since 1.8.0

Similar to getStarred, but organizes music according to ID3 tags.

Parameter Required Default Comment
musicFolderId No (Since 1.12.0) Only return results from the music folder with the given ID. See getMusicFolders.

Returns a <subsonic-response> element with a nested <starred2> element on success. Example.

search

http://your-server/rest/search Since 1.0.0
Deprecated since 1.4.0, use search2 instead.

Returns a listing of files matching the given search criteria. Supports paging through the result.

Parameter Required Default Comment
artist No Artist to search for.
album No Album to searh for.
title No Song title to search for.
any No Searches all fields.
count No 20 Maximum number of results to return.
offset No 0 Search result offset. Used for paging.
newerThan No Only return matches that are newer than this. Given as milliseconds since 1970.

Returns a <subsonic-response> element with a nested <searchResult> element on success. Example.

search2

http://your-server/rest/search2 Since 1.4.0

Returns albums, artists and songs matching the given search criteria. Supports paging through the result.

Parameter Required Default Comment
query Yes Search query.
artistCount No 20 Maximum number of artists to return.
artistOffset No 0 Search result offset for artists. Used for paging.
albumCount No 20 Maximum number of albums to return.
albumOffset No 0 Search result offset for albums. Used for paging.
songCount No 20 Maximum number of songs to return.
songOffset No 0 Search result offset for songs. Used for paging.
musicFolderId No (Since 1.12.0) Only return results from the music folder with the given ID. See getMusicFolders.

Returns a <subsonic-response> element with a nested <searchResult2> element on success. Example.

search3

http://your-server/rest/search3 Since 1.8.0

Similar to search2, but organizes music according to ID3 tags.

Parameter Required Default Comment
query Yes Search query.
artistCount No 20 Maximum number of artists to return.
artistOffset No 0 Search result offset for artists. Used for paging.
albumCount No 20 Maximum number of albums to return.
albumOffset No 0 Search result offset for albums. Used for paging.
songCount No 20 Maximum number of songs to return.
songOffset No 0 Search result offset for songs. Used for paging.
musicFolderId No (Since 1.12.0) Only return results from music folder with the given ID. See getMusicFolders.

Returns a <subsonic-response> element with a nested <searchResult3> element on success. Example.

getPlaylists

http://your-server/rest/getPlaylists Since 1.0.0

Returns all playlists a user is allowed to play.

Parameter Required Default Comment
username no (Since 1.8.0) If specified, return playlists for this user rather than for the authenticated user. The authenticated user must have admin role if this parameter is used.

Returns a <subsonic-response> element with a nested <playlists> element on success. Example.

getPlaylist

http://your-server/rest/getPlaylist Since 1.0.0

Returns a listing of files in a saved playlist.

Parameter Required Default Comment
id yes ID of the playlist to return, as obtained by getPlaylists.

Returns a <subsonic-response> element with a nested <playlist> element on success. Example.

createPlaylist

http://your-server/rest/createPlaylist Since 1.2.0

Creates (or updates) a playlist.

Parameter Required Default Comment
playlistId Yes (if updating) The playlist ID.
name Yes (if creating) The human-readable name of the playlist.
songId No ID of a song in the playlist. Use one songId parameter for each song in the playlist.

Since 1.14.0 the newly created/updated playlist is returned. In earlier versions an empty <subsonic-response> element is returned.

updatePlaylist

http://your-server/rest/updatePlaylist Since 1.8.0

Updates a playlist. Only the owner of a playlist is allowed to update it.

Parameter Required Default Comment
playlistId Yes The playlist ID.
name No The human-readable name of the playlist.
comment No The playlist comment.
public No true if the playlist should be visible to all users, false otherwise.
songIdToAdd No Add this song with this ID to the playlist. Multiple parameters allowed.
songIndexToRemove No Remove the song at this position in the playlist. Multiple parameters allowed.

Returns an empty <subsonic-response> element on success.

deletePlaylist

http://your-server/rest/deletePlaylist Since 1.2.0

Deletes a saved playlist.

Parameter Required Default Comment
id yes ID of the playlist to delete, as obtained by getPlaylists.

Returns an empty <subsonic-response> element on success.

stream

http://your-server/rest/stream Since 1.0.0

Streams a given media file.

Parameter Required Default Comment
id Yes A string which uniquely identifies the file to stream. Obtained by calls to getMusicDirectory.
maxBitRate No (Since 1.2.0) If specified, the server will attempt to limit the bitrate to this value, in kilobits per second. If set to zero, no limit is imposed.
format No (Since 1.6.0) Specifies the preferred target format (e.g., "mp3" or "flv") in case there are multiple applicable transcodings. Starting with 1.9.0 you can use the special value "raw" to disable transcoding.
timeOffset No Only applicable to video streaming. If specified, start streaming at the given offset (in seconds) into the video. Typically used to implement video skipping.
size No (Since 1.6.0) Only applicable to video streaming. Requested video size specified as WxH, for instance "640x480".
estimateContentLength No false (Since 1.8.0). If set to "true", the Content-Length HTTP header will be set to an estimated value for transcoded or downsampled media.
converted No false (Since 1.14.0) Only applicable to video streaming. Subsonic can optimize videos for streaming by converting them to MP4. If a conversion exists for the video in question, then setting this parameter to "true" will cause the converted video to be returned instead of the original.

Returns binary data on success, or an XML document on error (in which case the HTTP content type will start with "text/xml").

download

http://your-server/rest/download Since 1.0.0

Downloads a given media file. Similar to stream, but this method returns the original media data without transcoding or downsampling.

Parameter Required Default Comment
id Yes A string which uniquely identifies the file to download. Obtained by calls to getMusicDirectory.

Returns binary data on success, or an XML document on error (in which case the HTTP content type will start with "text/xml").

hls

http://your-server/rest/hls.m3u8 Since 1.8.0

Creates an HLS (HTTP Live Streaming) playlist used for streaming video or audio. HLS is a streaming protocol implemented by Apple and works by breaking the overall stream into a sequence of small HTTP-based file downloads. It's supported by iOS and newer versions of Android. This method also supports adaptive bitrate streaming, see the bitRate parameter.

Parameter Required Default Comment
id Yes A string which uniquely identifies the media file to stream.
bitRate No If specified, the server will attempt to limit the bitrate to this value, in kilobits per second. If this parameter is specified more than once, the server will create a variant playlist, suitable for adaptive bitrate streaming. The playlist will support streaming at all the specified bitrates. The server will automatically choose video dimensions that are suitable for the given bitrates. Since 1.9.0 you may explicitly request a certain width (480) and height (360) like so: bitRate=1000@480x360
audioTrack No The ID of the audio track to use. See getVideoInfo for how to get the list of available audio tracks for a video.

Returns an M3U8 playlist on success (content type "application/vnd.apple.mpegurl"), or an XML document on error (in which case the HTTP content type will start with "text/xml").

getCaptions

http://your-server/rest/getCaptions Since 1.14.0

Returns captions (subtitles) for a video. Use getVideoInfo to get a list of available captions.

Parameter Required Default Comment
id Yes The ID of the video.
format No Preferred captions format ("srt" or "vtt").

Returns the raw video captions.

getCoverArt

http://your-server/rest/getCoverArt Since 1.0.0

Returns a cover art image.

Parameter Required Default Comment
id Yes The ID of a song, album or artist.
size No If specified, scale image to this size.

Returns the cover art image in binary form.

getLyrics

http://your-server/rest/getLyrics Since 1.2.0

Searches for and returns lyrics for a given song.

Parameter Required Default Comment
artist No The artist name.
title No The song title.

Returns a <subsonic-response> element with a nested <lyrics> element on success. The <lyrics> element is empty if no matching lyrics was found. Example.

getAvatar

http://your-server/rest/getAvatar Since 1.8.0

Returns the avatar (personal image) for a user.

Parameter Required Default Comment
username Yes The user in question.

Returns the avatar image in binary form.

star

http://your-server/rest/star Since 1.8.0

Attaches a star to a song, album or artist.

Parameter Required Default Comment
id No The ID of the file (song) or folder (album/artist) to star. Multiple parameters allowed.
albumId No The ID of an album to star. Use this rather than id if the client accesses the media collection according to ID3 tags rather than file structure. Multiple parameters allowed.
artistId No The ID of an artist to star. Use this rather than id if the client accesses the media collection according to ID3 tags rather than file structure. Multiple parameters allowed.

Returns an empty <subsonic-response> element on success.

unstar

http://your-server/rest/unstar Since 1.8.0

Removes the star from a song, album or artist.

Parameter Required Default Comment
id No The ID of the file (song) or folder (album/artist) to unstar. Multiple parameters allowed.
albumId No The ID of an album to unstar. Use this rather than id if the client accesses the media collection according to ID3 tags rather than file structure. Multiple parameters allowed.
artistId No The ID of an artist to unstar. Use this rather than id if the client accesses the media collection according to ID3 tags rather than file structure. Multiple parameters allowed.

Returns an empty <subsonic-response> element on success.

setRating

http://your-server/rest/setRating Since 1.6.0

Sets the rating for a music file.

Parameter Required Default Comment
id Yes A string which uniquely identifies the file (song) or folder (album/artist) to rate.
rating Yes The rating between 1 and 5 (inclusive), or 0 to remove the rating.

Returns an empty <subsonic-response> element on success.

scrobble

http://your-server/rest/scrobble Since 1.5.0

Registers the local playback of one or more media files. Typically used when playing media that is cached on the client. This operation includes the following:

  • "Scrobbles" the media files on last.fm if the user has configured his/her last.fm credentials on the Subsonic server (Settings > Personal).
  • Updates the play count and last played timestamp for the media files. (Since 1.11.0)
  • Makes the media files appear in the "Now playing" page in the web app, and appear in the list of songs returned by getNowPlaying (Since 1.11.0)

Since 1.8.0 you may specify multiple id (and optionally time) parameters to scrobble multiple files.

Parameter Required Default Comment
id Yes A string which uniquely identifies the file to scrobble.
time No (Since 1.8.0) The time (in milliseconds since 1 Jan 1970) at which the song was listened to.
submission No True Whether this is a "submission" or a "now playing" notification.

Returns an empty <subsonic-response> element on success.

getShares

http://your-server/rest/getShares Since 1.6.0

Returns information about shared media this user is allowed to manage. Takes no extra parameters.

Returns a <subsonic-response> element with a nested <shares> element on success. Example.

createShare

http://your-server/rest/createShare Since 1.6.0

Creates a public URL that can be used by anyone to stream music or video from the Subsonic server. The URL is short and suitable for posting on Facebook, Twitter etc. Note: The user must be authorized to share (see Settings > Users > User is allowed to share files with anyone).

Parameter Required Default Comment
id Yes ID of a song, album or video to share. Use one id parameter for each entry to share.
description No A user-defined description that will be displayed to people visiting the shared media.
expires No The time at which the share expires. Given as milliseconds since 1970.

Returns a <subsonic-response> element with a nested <shares> element on success, which in turns contains a single <share> element for the newly created share. Example.

updateShare

http://your-server/rest/updateShare Since 1.6.0

Updates the description and/or expiration date for an existing share.

Parameter Required Default Comment
id Yes ID of the share to update.
description No A user-defined description that will be displayed to people visiting the shared media.
expires No The time at which the share expires. Given as milliseconds since 1970, or zero to remove the expiration.

Returns an empty <subsonic-response> element on success.

deleteShare

http://your-server/rest/deleteShare Since 1.6.0

Deletes an existing share.

Parameter Required Default Comment
id Yes ID of the share to delete.

Returns an empty <subsonic-response> element on success.

getPodcasts

http://your-server/rest/getPodcasts Since 1.6.0

Returns all Podcast channels the server subscribes to, and (optionally) their episodes. This method can also be used to return details for only one channel - refer to the id parameter. A typical use case for this method would be to first retrieve all channels without episodes, and then retrieve all episodes for the single channel the user selects.

Parameter Required Default Comment
includeEpisodes No true (Since 1.9.0) Whether to include Podcast episodes in the returned result.
id No (Since 1.9.0) If specified, only return the Podcast channel with this ID.

Returns a <subsonic-response> element with a nested <podcasts> element on success. Example.

getNewestPodcasts

http://your-server/rest/getNewestPodcasts Since 1.13.0

Returns the most recently published Podcast episodes.

Parameter Required Default Comment
count No 20 The maximum number of episodes to return.

Returns a <subsonic-response> element with a nested <newestPodcasts> element on success. Example.

refreshPodcasts

http://your-server/rest/refreshPodcasts Since 1.9.0

Requests the server to check for new Podcast episodes. Note: The user must be authorized for Podcast administration (see Settings > Users > User is allowed to administrate Podcasts).

Returns an empty <subsonic-response> element on success.

createPodcastChannel

http://your-server/rest/createPodcastChannel Since 1.9.0

Adds a new Podcast channel. Note: The user must be authorized for Podcast administration (see Settings > Users > User is allowed to administrate Podcasts).

Parameter Required Default Comment
url Yes The URL of the Podcast to add.

Returns an empty <subsonic-response> element on success.

deletePodcastChannel

http://your-server/rest/deletePodcastChannel Since 1.9.0

Deletes a Podcast channel. Note: The user must be authorized for Podcast administration (see Settings > Users > User is allowed to administrate Podcasts).

Parameter Required Default Comment
id Yes The ID of the Podcast channel to delete.

Returns an empty <subsonic-response> element on success.

deletePodcastEpisode

http://your-server/rest/deletePodcastEpisode Since 1.9.0

Deletes a Podcast episode. Note: The user must be authorized for Podcast administration (see Settings > Users > User is allowed to administrate Podcasts).

Parameter Required Default Comment
id Yes The ID of the Podcast episode to delete.

Returns an empty <subsonic-response> element on success.

downloadPodcastEpisode

http://your-server/rest/downloadPodcastEpisode Since 1.9.0

Request the server to start downloading a given Podcast episode. Note: The user must be authorized for Podcast administration (see Settings > Users > User is allowed to administrate Podcasts).

Parameter Required Default Comment
id Yes The ID of the Podcast episode to download.

Returns an empty <subsonic-response> element on success.

jukeboxControl

http://your-server/rest/jukeboxControl Since 1.2.0

Controls the jukebox, i.e., playback directly on the server's audio hardware. Note: The user must be authorized to control the jukebox (see Settings > Users > User is allowed to play files in jukebox mode).

Parameter Required Default Comment
action Yes The operation to perform. Must be one of: get, status (since 1.7.0), set (since 1.7.0), start, stop, skip, add, clear, remove, shuffle, setGain
index No Used by skip and remove. Zero-based index of the song to skip to or remove.
offset No (Since 1.7.0) Used by skip. Start playing this many seconds into the track.
id No Used by add and set. ID of song to add to the jukebox playlist. Use multiple id parameters to add many songs in the same request. (set is similar to a clear followed by a add, but will not change the currently playing track.)
gain No Used by setGain to control the playback volume. A float value between 0.0 and 1.0.

Returns a <jukeboxStatus> element on success, unless the get action is used, in which case a nested <jukeboxPlaylist> element is returned. Example 1. Example 2.

getInternetRadioStations

http://your-server/rest/getInternetRadioStations Since 1.9.0

Returns all internet radio stations. Takes no extra parameters.

Returns a <subsonic-response> element with a nested <internetRadioStations> element on success. Example.

createInternetRadioStation

http://your-server/rest/createInternetRadioStation Since 1.16.0

Adds a new internet radio station. Only users with admin privileges are allowed to call this method.

Parameter Required Default Comment
streamUrl Yes The stream URL for the station.
name Yes The user-defined name for the station.
homepageUrl No The home page URL for the station.

Returns an empty <subsonic-response> element on success.

updateInternetRadioStation

http://your-server/rest/updateInternetRadioStation Since 1.16.0

Updates an existing internet radio station. Only users with admin privileges are allowed to call this method.

Parameter Required Default Comment
id Yes The ID for the station.
streamUrl Yes The stream URL for the station.
name Yes The user-defined name for the station.
homepageUrl No The home page URL for the station.

Returns an empty <subsonic-response> element on success.

deleteInternetRadioStation

http://your-server/rest/deleteInternetRadioStation Since 1.16.0

Deletes an existing internet radio station. Only users with admin privileges are allowed to call this method.

Parameter Required Default Comment
id Yes The ID for the station.

Returns an empty <subsonic-response> element on success.

getChatMessages

http://your-server/rest/getChatMessages Since 1.2.0

Returns the current visible (non-expired) chat messages.

Parameter Required Default Comment
since No Only return messages newer than this time (in millis since Jan 1 1970).

Returns a <subsonic-response> element with a nested <chatMessages> element on success. Example.

addChatMessage

http://your-server/rest/addChatMessage Since 1.2.0

Adds a message to the chat log.

Parameter Required Default Comment
message Yes The chat message.

Returns an empty <subsonic-response> element on success.

getUser

http://your-server/rest/getUser Since 1.3.0

Get details about a given user, including which authorization roles and folder access it has. Can be used to enable/disable certain features in the client, such as jukebox control.

Parameter Required Default Comment
username Yes The name of the user to retrieve. You can only retrieve your own user unless you have admin privileges.

Returns a <subsonic-response> element with a nested <user> element on success. Example.

getUsers

http://your-server/rest/getUsers Since 1.8.0

Get details about all users, including which authorization roles and folder access they have. Only users with admin privileges are allowed to call this method.

Returns a <subsonic-response> element with a nested <users> element on success. Example.

createUser

http://your-server/rest/createUser Since 1.1.0

Creates a new Subsonic user, using the following parameters:

Parameter Required Default Comment
username Yes The name of the new user.
password Yes The password of the new user, either in clear text of hex-encoded (see above).
email Yes The email address of the new user.
ldapAuthenticated No false Whether the user is authenicated in LDAP.
adminRole No false Whether the user is administrator.
settingsRole No true Whether the user is allowed to change personal settings and password.
streamRole No true Whether the user is allowed to play files.
jukeboxRole No false Whether the user is allowed to play files in jukebox mode.
downloadRole No false Whether the user is allowed to download files.
uploadRole No false Whether the user is allowed to upload files.
playlistRole No false Whether the user is allowed to create and delete playlists. Since 1.8.0, changing this role has no effect.
coverArtRole No false Whether the user is allowed to change cover art and tags.
commentRole No false Whether the user is allowed to create and edit comments and ratings.
podcastRole No false Whether the user is allowed to administrate Podcasts.
shareRole No false (Since 1.8.0) Whether the user is allowed to share files with anyone.
videoConversionRole No false (Since 1.15.0) Whether the user is allowed to start video conversions.
musicFolderId No All folders (Since 1.12.0) IDs of the music folders the user is allowed access to. Include the parameter once for each folder.

Returns an empty <subsonic-response> element on success.

updateUser

http://your-server/rest/updateUser Since 1.10.1

Modifies an existing Subsonic user, using the following parameters:

Parameter Required Default Comment
username Yes The name of the user.
password No The password of the user, either in clear text of hex-encoded (see above).
email No The email address of the user.
ldapAuthenticated No Whether the user is authenicated in LDAP.
adminRole No Whether the user is administrator.
settingsRole No Whether the user is allowed to change personal settings and password.
streamRole No Whether the user is allowed to play files.
jukeboxRole No Whether the user is allowed to play files in jukebox mode.
downloadRole No Whether the user is allowed to download files.
uploadRole No Whether the user is allowed to upload files.
coverArtRole No Whether the user is allowed to change cover art and tags.
commentRole No Whether the user is allowed to create and edit comments and ratings.
podcastRole No Whether the user is allowed to administrate Podcasts.
shareRole No Whether the user is allowed to share files with anyone.
videoConversionRole No false (Since 1.15.0) Whether the user is allowed to start video conversions.
musicFolderId No (Since 1.12.0) IDs of the music folders the user is allowed access to. Include the parameter once for each folder.
maxBitRate No (Since 1.13.0) The maximum bit rate (in Kbps) for the user. Audio streams of higher bit rates are automatically downsampled to this bit rate. Legal values: 0 (no limit), 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320.

Returns an empty <subsonic-response> element on success.

deleteUser

http://your-server/rest/deleteUser Since 1.3.0

Deletes an existing Subsonic user, using the following parameters:

Parameter Required Default Comment
username Yes The name of the user to delete.

Returns an empty <subsonic-response> element on success.

changePassword

http://your-server/rest/changePassword Since 1.1.0

Changes the password of an existing Subsonic user, using the following parameters. You can only change your own password unless you have admin privileges.

Parameter Required Default Comment
username Yes The name of the user which should change its password.
password Yes The new password of the new user, either in clear text of hex-encoded (see above).

Returns an empty <subsonic-response> element on success.

getBookmarks

http://your-server/rest/getBookmarks Since 1.9.0

Returns all bookmarks for this user. A bookmark is a position within a certain media file.

Returns a <subsonic-response> element with a nested <bookmarks> element on success. Example.

createBookmark

http://your-server/rest/createBookmark Since 1.9.0

Creates or updates a bookmark (a position within a media file). Bookmarks are personal and not visible to other users.

Parameter Required Default Comment
id Yes ID of the media file to bookmark. If a bookmark already exists for this file it will be overwritten.
position Yes The position (in milliseconds) within the media file.
comment No A user-defined comment.

Returns an empty <subsonic-response> element on success.

deleteBookmark

http://your-server/rest/deleteBookmark Since 1.9.0

Deletes the bookmark for a given file.

Parameter Required Default Comment
id Yes ID of the media file for which to delete the bookmark. Other users' bookmarks are not affected.

Returns an empty <subsonic-response> element on success.

getPlayQueue

http://your-server/rest/getPlayQueue Since 1.12.0

Returns the state of the play queue for this user (as set by savePlayQueue). This includes the tracks in the play queue, the currently playing track, and the position within this track. Typically used to allow a user to move between different clients/apps while retaining the same play queue (for instance when listening to an audio book).

Returns a <subsonic-response> element with a nested <playQueue> element on success, or an empty <subsonic-response> if no play queue has been saved. Example.

savePlayQueue

http://your-server/rest/savePlayQueue Since 1.12.0

Saves the state of the play queue for this user. This includes the tracks in the play queue, the currently playing track, and the position within this track. Typically used to allow a user to move between different clients/apps while retaining the same play queue (for instance when listening to an audio book).

Parameter Required Default Comment
id Yes ID of a song in the play queue. Use one id parameter for each song in the play queue.
current No The ID of the current playing song.
position No The position in milliseconds within the currently playing song.

Returns an empty <subsonic-response> element on success.

getScanStatus

http://your-server/rest/getScanStatus Since 1.15.0

Returns the current status for media library scanning. Takes no extra parameters.

Returns a <subsonic-response> element with a nested <scanStatus> element on success. Example.

startScan

http://your-server/rest/startScan Since 1.15.0

Initiates a rescan of the media libraries. Takes no extra parameters.

Returns a <subsonic-response> element with a nested <scanStatus> element on success. Example.