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. | |
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.7 | 1.8.0 |
| 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.
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,
getArtists,
getArtist,
getAlbum,
getSong,
getVideos
|
| Album/song lists |
getAlbumList,
getAlbumList2,
getRandomSongs,
getNowPlaying,
getStarred,
getStarred2
|
| Searching |
search,
search2,
search3
|
| Playlists |
getPlaylists,
getPlaylist,
createPlaylist,
updatePlaylist,
deletePlaylist
|
| Media retrieval |
stream,
download,
getCoverArt,
getLyrics,
getAvatar
|
| Media annotation |
star,
unstar,
setRating,
scrobble
|
| Sharing |
getShares,
createShare,
updateShare,
deleteShare
|
| Podcast |
getPodcasts
|
| Jukebox |
jukeboxControl
|
| Chat |
getChatMessages,
addChatMessage
|
| User management |
getUser,
createUser,
deleteUser,
changePassword
|