Getting Started

• Introduction
• Implementation
• Authentication
• Error handling
• REST Versions
• File structure vs ID3 tags
• Methods

Introduction

The Madsonic 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 2.0.0 this should only be used for testing purposes.
t	Yes*		(Since 2.0.0) The authentication token computed as md5(password + salt). See below for details.
s	Yes*		(Since 2.0.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 madsonic-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, jsonp. 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 madsonic-rest-api.xsd schema. The XML documents are encoded with UTF-8.

Implementation

Since build > 6.0.7300 you can make your calls on diffrent REST API levels.

Example

emulated Subsonic REST 1.x.x http://localhost:4040/rest/getApi.view?f=xml
native Madsonic REST 2.x.x http://localhost:4040/rest2/getApi.view?f=json

Result

<?xml version="1.0" encoding="UTF-8"?>
  <madsonic-response xmlns="http://madsonic.org/restapi" status="ok">
  <api>
      <rest type="madsonic" version="2.5.0"/>
      <rest type="subsonic" version="1.14.0"/>
  <api>
</madsonic-response>		

REST API layer call syntax

To difference on the client side each madsonic-responde have a attribute type with the value madsonic or subsonic

REST 1.x.x service

Example

http://localhost:4040/rest/ping.view?u=admin&p=admin&v=1.0.0&c=rest&f=xml
http://localhost:4040/rest/ping.view?u=admin&p=enc:61646d696e&v=1.10.0&c=rest&f=xml

Result

<?xml version="1.0" encoding="UTF-8"?>
  <subsonic-response xmlns="http://subsonic.org/restapi" status="ok" version="1.13.0" type="subsonic">

REST 2.x.x service

Example

http://localhost:4040/rest2/ping.view?u=admin&p=admin&v=2.0.0&c=rest&f=xml
http://localhost:4040/rest2/ping.view?u=admin&p=enc:61646d696e&v=2.0.0&c=rest&f=xml
http://localhost:4040/rest2/ping.view?u=admin&t=abf0abaeeb6ac8328828576c64c8cc2a&s=xfhn8gf4gv&v=2.0.0&c=rest&f=xml

Result

<?xml version="1.0" encoding="UTF-8"?>
  <madsonic-response xmlns="http://madsonic.org/restapi" status="ok" version="2.0.0" type="madsonic">

REST with difference

REST wrong usage

Recommended use

Authentication

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

Starting with API version 2.0.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.
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 secret and the random salt is xfhn8gf4gv, then token = md5("secretxfhn8gf4gv") = 8a4ff6068f3b09c6a302d4d58e02d6f0.
The corresponding request URL then becomes:

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 <madsonic-response> root element will be set to failed instead of ok. For example:

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

The following error codes are defined:

Code	Description
0	A generic error.
10	Required parameter is missing.
20	Incompatible REST protocol version. Client must upgrade.
30	Incompatible 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 Madsonic server is over. Please upgrade to Madsonic Premium. Visit madsonic.org for details.
70	The requested data was not found.

Versions

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

Madsonic	REST API
Server 6.3.x	1.15.0 & 2.6.x
Server 6.2	1.14.0 & 2.5.0
Server 6.1	1.14.0 & 2.5.0
Server 6.0	1.13.0 & 2.2.0
Server 5.1	1.10.5
Server 5.0	1.9.0
Server 4.9	1.8.0

Subsonic	REST API
Server 6.1.x	1.15.0
Server 6.0	1.14.0
Server 5.3	1.13.0
Server 4.9	1.10.2
Server 4.8	1.9.0
Server 4.6	1.7.0

Note that a Madsonic 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.0,
it supports client versions 2.0.0, 2.1.0 and 2.2.0, but not versions 1.x.x, 2.3+ or 3.x.x.
The third part of the version number is not used to determine compatibility.

File structure vs ID3 tags

Starting with version 2.0.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

REST	getApi
System	ping, getLicense
Browsing	getMusicFolders, getIndexes, getMusicDirectory, getGenres, getArtistGenres, getArtists, getArtist, getAlbum, getSong, getVideos, getImage
Metadata	getArtistInfo, getArtistInfoID3, getAlbumInfo, getAlbumInfoID3, getVideoInfo
Similar	getSimilarSongs, getSimilarSongsID3 getSimilarArtists, getSimilarArtistsID3
Artist lists	getArtist, getArtistsByGenre
Album lists	getAlbumList, getAlbumListID3 getRandomAlbumsID3
Song lists	getRandomSongs, getSongsByGenre, getNewaddedSongs, getLastplayedSongs, getMostplayedSongs, getTopplayedSongs, getFollowmeSongs, getNowPlaying, getStarred, getStarredID3
Searching	search, searchID3
Playlists	getPlaylists, getPlaylist, createPlaylist, updatePlaylist, deletePlaylist
Media retrieval	stream, hls, dash, download, getCoverArt, getCaptions, getLyrics, getAvatar
Media annotation	star, unstar, love, unlove, setRating, scrobble
Sharing	getShares, createShare, updateShare, deleteShare
Podcast	getPodcasts, getNewestPodcasts, refreshPodcasts, createPodcastChannel, deletePodcastChannel, deletePodcastEpisode, downloadPodcastEpisode
Jukebox	jukeboxControl
virtual Jukebox	nodeControl
Nodes	getNodeList
Internet radio	getInternetRadioStations
Chat	getChatMessages, addChatMessage
User management	getUser, getUsers, createUser, updateUser, deleteUser, changePassword
Bookmarks	getBookmarks, createBookmark, deleteBookmark, getPlayQueue, savePlayQueue
Scanning	scanStatus, startRescan

getApi

http://localhost:4040/rest2/getApi.view

Since 2.0.0

Used to test connectivity with the server and get supported REST version. Takes no extra parameters or user authentication.

Returns a <madsonic-response> element with a nested <api> element on success. Example.

ping

http://localhost:4040/rest2/ping.view

Since 1.0.0

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

Returns an empty <madsonic-response> element on success. XML Example, JSON Example.

getLicense

http://localhost:4040/rest2/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 must upgrade to Madsonic Premium.

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

getMusicFolders

http://localhost:4040/rest2/getMusicFolders.view

Since 1.0.0

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

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

getIndexes

http://localhost:4040/rest2/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 (in milliseconds since 1 Jan 1970).

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

getMusicDirectory

http://localhost:4040/rest2/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 <madsonic-response> element with a nested <directory> element on success. Example 1, Example 2.

getGenres

http://localhost:4040/rest2/getGenres.view

Since 1.9.0

Returns all genres.

Parameter	Required	Default	Comment
sortBy	No	song	(Since 2.7.0) Allow to sort by: song, album, artist, name
excludeNotPresent	No	false	(Since 2.7.0) Whether to return genres that are not present.

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

getArtistGenres

http://localhost:4040/rest2/getArtistGenres.view

Since 2.0.0

Returns all Artists genres.

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

getArtists

http://localhost:4040/rest2/getArtists.view

Since 1.8.0

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

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

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

getArtist

http://localhost:4040/rest2/getArtist.view

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.
musicFolderId	No		(Since 2.7.0) If specified, only return artists in the music folder with the given ID. See getMusicFolders

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

getAlbum

http://localhost:4040/rest2/getAlbum.view

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 <madsonic-response> element with a nested <album> element on success. Example.

getSong

http://localhost:4040/rest2/getSong.view

Since 1.8.0

Returns details for a song.

Parameter	Required	Default	Comment
id	Yes		The song ID.

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

getVideos

http://localhost:4040/rest2/getVideos.view

Since 1.8.0

Returns all video files.

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

getImage

http://localhost:4040/rest2/getImage.view

Since 2.0.0

Returns details for a image.

Parameter	Required	Default	Comment
id	Yes		The Image ID.

Returns a <madsonic-response> element with a nested <images> element on success. Example.

getArtistInfo

http://localhost:4040/rest2/getArtistInfo.view

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 <madsonic-response> element with a nested <artistInfo> element on success. Example.

getArtistInfoID3

http://localhost:4040/rest2/getArtistInfoID3.view

Since 2.0.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 <madsonic-response> element with a nested <artistInfoID3> element on success. Example.

getAlbumInfo

http://localhost:4040/rest2/getAlbumInfo.view

Since 2.1.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 <madsonic-response> element with a nested <albumInfo> element on success. Example.

getAlbumInfoID3

http://localhost:4040/rest2/getAlbumInfoID3.view

Since 2.1.0

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

Parameter	Required	Default	Comment
id	Yes		The album ID.

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

getVideoInfo

http://localhost:4040/rest2/getVideoInfo.view

Since 2.5.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 <madsonic-response> element with a nested <videoInfo> element on success. Example.

getSimilarSongs

http://localhost:4040/rest2/getSimilarSongs.view

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 <madsonic-response> element with a nested <similarSongs> element on success. Example.

getSimilarSongsID3

http://localhost:4040/rest2/getSimilarSongsID3.view

Since 2.0.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 <madsonic-response> element with a nested <similarSongsID3> element on success. Example.

getSimilarArtists

http://localhost:4040/rest2/getSimilarArtists.view

Since 2.0.0

Returns similar artists, using data from last.fm.

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 <madsonic-response> element with a nested <similarArtists> element on success. Example.

getSimilarArtistsID3

http://localhost:4040/rest2/getSimilarArtistsID3.view

Since 2.0.0

Similar to getSimilarArtists, 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 <madsonic-response> element with a nested <similarArtistsID3> element on success. Example.

getArtistsByGenre

http://localhost:4040/rest2/getArtistsByGenre.view

Since 1.10.5

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

Parameter	Required	Default	Comment
genre	Yes		The genre, as returned by getArtistGenres.
count	No	10	The number of artists to return. Max 500.
offset	No	0	The list offset. Useful if you for example want to page through the list of newest artists.

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

getAlbumList

http://localhost:4040/rest2/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, 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".

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

getAlbumListID3

http://localhost:4040/rest2/getAlbumListID3.view

Since 2.0.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. 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 2.7.0) If specified, only return artists in the music folder with the given ID. See getMusicFolders

Returns a <madsonic-response> element with a nested <albumListID3> element on success. Example.

getRandomAlbumsID3

http://localhost:4040/rest2/getRandomAlbumsID3.view

Since 2.6.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 <madsonic-response> element with a nested <randomAlbumsID3> element on success. Example.

getRandomSongs

http://localhost:4040/rest2/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 <madsonic-response> element with a nested <randomSongs> element on success. Example.

getSongsByGenre

http://localhost:4040/rest2/getSongsByGenre.view

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.

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

getNewaddedSongs

http://localhost:4040/rest2/getNewaddedSongs.view

Since 2.0.0

Returns new added songs.

Parameter	Required	Default	Comment
count	No	20	The maximum number of songs to return. Max 500.
offset	No	0	The offset. Useful if you want to page through the songs.

Returns a <madsonic-response> element with a nested <newaddedSongs> element on success. Example.

getLastplayedSongs

http://localhost:4040/rest2/getLastplayedSongs.view

Since 2.0.0

Returns last played songs.

Parameter	Required	Default	Comment
count	No	20	The maximum number of songs to return. Max 500.
offset	No	0	The offset. Useful if you want to page through the songs.

Returns a <madsonic-response> element with a nested <lastplayedSongs> element on success. Example.

getMostplayedSongs

http://localhost:4040/rest2/getMostplayedSongs.view

Since 2.0.1

Returns most played songs.

Parameter	Required	Default	Comment
count	No	20	The maximum number of songs to return. Max 500.
offset	No	0	The offset. Useful if you want to page through the songs.

Returns a <madsonic-response> element with a nested <mostplayedSongs> element on success. Example.

getTopplayedSongs

http://localhost:4040/rest2/getTopplayedSongs.view

Since 2.0.1

Returns top played songs.

Parameter	Required	Default	Comment
count	No	20	The maximum number of songs to return. Max 500.
offset	No	0	The offset. Useful if you want to page through the songs.

Returns a <madsonic-response> element with a nested <topplayedSongs> element on success. Example.

getFollowmeSongs

http://localhost:4040/rest2/getFollowmeSongs.view

Since 2.0.1

Returns a random collection of songs from the given song using data from Madsonic FollowMe.

Parameter	Required	Default	Comment
id	Yes		The song ID.

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

getNowPlaying

http://localhost:4040/rest2/getNowPlaying.view

Since 1.0.0

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

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

getStarred

http://localhost:4040/rest2/getStarred.view

Since 1.8.0

Returns starred songs, albums and artists.

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

getStarredID3

http://localhost:4040/rest2/getStarredID3.view

Since 2.0.0

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

Returns a <madsonic-response> element with a nested <starredID3> element on success. Example.

search

http://localhost:4040/rest2/search.view

Since 2.0.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 <madsonic-response> element with a nested <searchResult> element on success. Example.

searchID3

http://localhost:4040/rest2/searchID3.view

Since 2.0.0

Similar to search, 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.

Returns a <madsonic-response> element with a nested <searchResultID3> element on success. Example.

getPlaylists

http://localhost:4040/rest2/getPlaylists.view

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 <madsonic-response> element with a nested <playlists> element on success. Example.

getPlaylist

http://localhost:4040/rest2/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 <madsonic-response> element with a nested <playlist> element on success. Example.

createPlaylist

http://localhost:4040/rest2/createPlaylist.view

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	Yes		ID of a song in the playlist. Use one songId parameter for each song in the playlist.

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

updatePlaylist

http://localhost:4040/rest2/updatePlaylist.view

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.
usernameToAdd	No		(Since 2.6.1) Allow this user to listen to this playlist. Multiple parameters allowed.
usernameToRemove	No		(Since 2.6.1) Disallow this user to listen to this playlist. Multiple parameters allowed.
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 <madsonic-response> element on success.

deletePlaylist

http://localhost:4040/rest2/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 <madsonic-response> element on success.

stream

http://localhost:4040/rest2/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. 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.

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://localhost:4040/rest2/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").

dash

http://localhost:4040/rest2/dash.xml

Since 2.0.0

Creates an DASH (MPEG-DASH) playlist used for streaming video. MPEG-DASH is the first adaptive bit-rate HTTP-based streaming solution that is an international standard.

Parameter	Required	Default	Comment
id	Yes		A string which uniquely identifies the media file to stream.

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

download

http://localhost:4040/rest2/download.view

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

getCoverArt

http://localhost:4040/rest2/getCoverArt.view

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.

getCaptions

http://localhost:4040/rest2/getCaptions.view

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

getLyrics

http://localhost:4040/rest2/getLyrics.view

Since 1.2.0

Searches for and returns lyrics for a given song.

Parameter	Required	Default	Comment
id	No		The media id instead of artist and title.
artist	No		The artist name.
title	No		The song title.

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

getAvatar

http://localhost:4040/rest2/getAvatar.view

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://localhost:4040/rest2/star.view

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

unstar

http://localhost:4040/rest2/unstar.view

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

love

http://localhost:4040/rest2/love.view

Since 2.7.0

Attaches a love to a song.

Parameter	Required	Default	Comment
id	No		The ID of the file (song) or folder (album/artist) to love. Multiple parameters allowed.

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

unlove

http://localhost:4040/rest2/unlove.view

Since 1.8.0

Removes the love from a song.

Parameter	Required	Default	Comment
id	No		The ID of the file (song) to unlove. Multiple parameters allowed.

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

setRating

http://localhost:4040/rest2/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 <madsonic-response> element on success.

scrobble

http://localhost:4040/rest2/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 Madsonic server (Settings > Personal).

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

getShares

http://localhost:4040/rest2/getShares.view

Since 1.6.0

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

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

createShare

http://localhost:4040/rest2/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 <madsonic-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://localhost:4040/rest2/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 <madsonic-response> element on success.

deleteShare

http://localhost:4040/rest2/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 <madsonic-response> element on success.

getPodcasts

http://localhost:4040/rest2/getPodcasts.view

Since 2.0.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	Whether to include Podcast episodes in the returned result.
id	No		If specified, only return the Podcast channel with this ID.

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

getNewestPodcasts

http://localhost:4040/rest2/getNewestPodcasts.view

Since 2.0.0

Returns the most recently published Podcast episodes.

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

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

refreshPodcasts

http://localhost:4040/rest2/refreshPodcasts.view

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

createPodcastChannel

http://localhost:4040/rest2/createPodcastChannel.view

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

deletePodcastChannel

http://localhost:4040/rest2/deletePodcastChannel.view

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

deletePodcastEpisode

http://localhost:4040/rest2/deletePodcastEpisode.view

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

downloadPodcastEpisode

http://localhost:4040/rest2/downloadPodcastEpisode.view

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

jukeboxControl

http://localhost:4040/rest2/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, set, 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		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.

nodeControl

http://localhost:4040/rest2/nodeControl.view

Since 2.4.0

Controls the virtual jukebox. Note: The user must be authorized to control the remote 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, set, 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		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 <nodeStatus> element on success, unless the get action is used, in which case a nested <nodePlaylist> element is returned. Example 1. Example 2.

getNodeList

http://localhost:4040/rest2/getNodeList.view

Since 2.4.0

Returns all nodes.

Returns a <madsonic-response> element with a nested <node> element on success. Example.

getInternetRadioStations

http://localhost:4040/rest2/getInternetRadioStations.view

Since 1.9.0

Returns all internet radio stations. Takes no extra parameters.

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

getChatMessages

http://localhost:4040/rest2/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 <madsonic-response> element with a nested <chatMessages> element on success. Example.

addChatMessage

http://localhost:4040/rest2/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 <madsonic-response> element on success.

getUser

http://localhost:4040/rest2/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 <madsonic-response> element with a nested <user> element on success. Example.

getUsers

http://localhost:4040/rest2/getUsers.view

Since 1.8.0

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

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

createUser

http://localhost:4040/rest2/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).
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 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.
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.
lastFMRole	No	false	(Since 1.10.2) Whether the user is allowed to use Last.FM calls.

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

updateUser

http://localhost:4040/rest2/updateUser.view

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 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.
lastFMRole	No	false	(Since 1.10.2) Whether the user is allowed to use Last.FM calls.

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

deleteUser

http://localhost:4040/rest2/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 <madsonic-response> element on success.

changePassword

http://localhost:4040/rest2/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 <madsonic-response> element on success.

getBookmarks

http://localhost:4040/rest2/getBookmarks.view

Since 1.9.0

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

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

createBookmark

http://localhost:4040/rest2/createBookmark.view

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

deleteBookmark

http://localhost:4040/rest2/deleteBookmark.view

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

getPlayQueue

http://localhost:4040/rest2/getPlayQueue.view

Since 2.0.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 <madsonic-response> element with a nested <playQueue> element on success, or an empty <madsonic-response> if no play queue has been saved. Example.

savePlayQueue

http://localhost:4040/rest2/savePlayQueue.view

Since 2.0.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 <madsonic-response> element on success.

scanStatus

http://localhost:4040/rest2/scanStatus.view

Since 2.0.0

Display the server status of scanning. Takes no extra parameters.

Returns a <madsonic-response> element with a nested <scan> element on success. Example 1, Example 2.

startRescan

http://localhost:4040/rest2/startRescan.view

Since 2.0.0

Start the server media scanning. Takes no extra parameters.

Returns a <madsonic-response> element with a nested <scan> element on success. Example 1.

---