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.
Donate
Love Subsonic? Support continued development and maintenance by giving a donation.
Donors get access to premium features like:
- Unlimited use of the Subsonic Android app.
- Your personal server address: yourname.subsonic.org
- No ads in the web interface.
The suggested donation amount is €20, but you can give any amount you like. €10, €15, €20, €25, €30

