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 app is built using the Subsonic API.

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.

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

Also 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 is over. Please donate to get a license key.

ping

http://your-server/rest/ping.view

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

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

getLicense

http://your-server/rest/getLicense.view

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

getMusicFolders

http://your-server/rest/getMusicFolders.view

Returns all configured music folders. Takes no extra parameters.

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

getNowPlaying

http://your-server/rest/getNowPlaying.view

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.

getIndexes

http://your-server/rest/getIndexes.view

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

getMusicDirectory

http://your-server/rest/getMusicDirectory.view

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 <musicFolder> element on success.

search

http://your-server/rest/search.view

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.

getPlaylists

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

Returns the ID and name of all saved playlists.

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

getPlaylist

http://your-server/rest/getPlaylist.view

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.

download

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

Downloads a given music 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.

stream

http://your-server/rest/stream.view

Streams a given music file.

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

Returns binary data on success.

getCoverArt

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

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.

changePassword

http://your-server/rest/changePassword.view

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

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.

createUser

http://your-server/rest/createUser.view

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.

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