Subsonic API

The Subsonic API allows anyone to build their own programs using Subsonic as the server, whether they're on the web, the desktop or on mobile devices. As an example, the Subsonic Android and iPhone 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.
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.

For example:

http://your-server/rest/getIndexes.view?u=joe&p=sesame&v=1.1.0&c=myapp, or
http://your-server/rest/getIndexes.view?u=joe&p=enc:736573616d65&v=1.1.0&c=myapp

Starting with API version 1.2.0 it is no longer necessary to send the username and password as part of the URL. Instead, HTTP Basic authentication could be used. (Only preemptive authentication is supported, meaning that the credentials should be supplied by the client without being challenged for it.)

Note that UTF-8 should be used when sending parameters to API methods. The XML returned will also be encoded with UTF-8.

All methods (except those that return binary data) returns XML documents conforming to the subsonic-rest-api.xsd schema. This schema (as well as example XML documents) can be found at http://your-server/xsd/

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.
50	User is not authorized for the given operation.
60	The trial period for the Subsonic server is over. Please donate to get a license key. 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
4.6	1.7.0
4.5	1.6.0
4.3.1	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.0.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.

List of API methods

ping

http://your-server/rest/ping.view
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.view
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 can give a donation to the Subsonic project.

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

getMusicFolders

http://your-server/rest/getMusicFolders.view
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.

getNowPlaying

http://your-server/rest/getNowPlaying.view
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.

getIndexes

http://your-server/rest/getIndexes.view
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.

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

getMusicDirectory

http://your-server/rest/getMusicDirectory.view
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.

search

http://your-server/rest/search.view
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.view
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.

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

getPlaylists

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

Returns the ID and name of all saved playlists.

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

getPlaylist

http://your-server/rest/getPlaylist.view
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.view
Since 1.2.0

Creates or updates a saved playlist. Note: The user must be authorized to create playlists (see Settings > Users > User is allowed to create and delete playlists).

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

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

deletePlaylist

http://your-server/rest/deletePlaylist.view
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.

download

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

Downloads a given media file.

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").

stream

http://your-server/rest/stream.view
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.
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".

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

getCoverArt

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

Returns a cover art image.

Parameter	Required	Default	Comment
id	Yes		A string which uniquely identifies the cover art file to download. Obtained by calls to getMusicDirectory.
size	No		If specified, scale image to this size.

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

scrobble

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

"Scrobbles" a given music file on last.fm. Requires that the user has configured his/her last.fm credentials on the Subsonic server (Settings > Personal).

Parameter	Required	Default	Comment
id	Yes		A string which uniquely identifies the file to scrobble.
submission	No	True	Whether this is a "submission" or a "now playing" notification.

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

changePassword

http://your-server/rest/changePassword.view
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.

getUser

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

Get details about a given user, including which authorization roles 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.

createUser

http://your-server/rest/createUser.view
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).
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 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.
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.

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

deleteUser

http://your-server/rest/deleteUser.view
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.

getChatMessages

http://your-server/rest/getChatMessages.view
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.view
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.

getAlbumList

http://your-server/rest/getAlbumList.view
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.
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. Max 5000.

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

getRandomSongs

http://your-server/rest/getRandomSongs.view
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.

getLyrics

http://your-server/rest/getLyrics.view
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.

jukeboxControl

http://your-server/rest/jukeboxControl.view
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.

getPodcasts

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

Returns all podcast channels the server subscribes to and their episodes. Takes no extra parameters.

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

getShares

http://your-server/rest/getShares.view
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.view
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.view
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.view
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.

setRating

http://your-server/rest/setRating.view
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.