This is the multi-page printable view of this section. Click here to print.
Endpoints
Low level endpoints documentation.
- 1: addChatMessage
- 2: changePassword
- 3: createBookmark
- 4: createInternetRadioStation
- 5: createPlaylist
- 6: createPodcastChannel
- 7: createShare
- 8: createUser
- 9: deleteBookmark
- 10: deleteInternetRadioStation
- 11: deletePlaylist
- 12: deletePodcastChannel
- 13: deletePodcastEpisode
- 14: deleteShare
- 15: deleteUser
- 16: download
- 17: downloadPodcastEpisode
- 18: getAlbum
- 19: getAlbumInfo
- 20: getAlbumInfo2
- 21: getAlbumList
- 22: getAlbumList2
- 23: getArtist
- 24: getArtistInfo
- 25: getArtistInfo2
- 26: getArtists
- 27: getAvatar
- 28: getBookmarks
- 29: getCaptions
- 30: getChatMessages
- 31: getCoverArt
- 32: getGenres
- 33: getIndexes
- 34: getInternetRadioStations
- 35: getLicense
- 36: getLyrics
- 37: getLyricsBySongId
- 38: getMusicDirectory
- 39: getMusicFolders
- 40: getNewestPodcasts
- 41: getNowPlaying
- 42: getOpenSubsonicExtensions
- 43: getPlaylist
- 44: getPlaylists
- 45: getPlayQueue
- 46: getPodcasts
- 47: getRandomSongs
- 48: getScanStatus
- 49: getShares
- 50: getSimilarSongs
- 51: getSimilarSongs2
- 52: getSong
- 53: getSongsByGenre
- 54: getStarred
- 55: getStarred2
- 56: getTopSongs
- 57: getUser
- 58: getUsers
- 59: getVideoInfo
- 60: getVideos
- 61: hls
- 62: jukeboxControl
- 63: ping
- 64: refreshPodcasts
- 65: savePlayQueue
- 66: scrobble
- 67: search
- 68: search2
- 69: search3
- 70: setRating
- 71: star
- 72: startScan
- 73: stream
- 74: tokenInfo
- 75: unstar
- 76: updateInternetRadioStation
- 77: updatePlaylist
- 78: updateShare
- 79: updateUser
1 - addChatMessage
Adds a message to the chat log.
http://your-server/rest/addChatMessage Since 1.2.0
Adds a message to the chat log.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
message |
Yes | The chat message. |
Example
http://your-server/rest/addChatMessage.view?message=hello&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}2 - changePassword
Changes the password of an existing user on the server.
http://your-server/rest/changePassword Since 1.1.0
Changes the password of an existing user on the server, using the following parameters. You can only change your own password unless you have admin privileges.
Parameters
| Parameter | Req. | OpenS. | 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). |
Example
http://your-server/rest/changePassword.view?username=demo&password=password&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}3 - createBookmark
Creates or updates a bookmark.
http://your-server/rest/createBookmark Since 1.9.0
Creates or updates a bookmark (a position within a media file). Bookmarks are personal and not visible to other users.
Parameters
| Parameter | Req. | OpenS. | 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. |
Example
http://your-server/rest/createBookmark.view?id=123&position=12&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}4 - createInternetRadioStation
Adds a new internet radio station.
http://your-server/rest/createInternetRadioStation Since 1.16.0
Adds a new internet radio station. Only users with admin privileges are allowed to call this method.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
streamUrl |
Yes | The stream URL for the station. | ||
name |
Yes | The user-defined name for the station. | ||
homepageUrl |
No | The home page URL for the station. |
Example
http://your-server/rest/createInternetRadioStation.view?streamUrl=url&name=radio&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}5 - createPlaylist
Creates (or updates) a playlist.
http://your-server/rest/createPlaylist Since 1.2.0
Creates (or updates) a playlist.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
playlistId |
Yes (if updating) | The playlist ID. | ||
name |
Yes (if creating) | The human-readable name of the playlist. | ||
songId |
No | ID of a song in the playlist. Use one songId parameter for each song in the playlist. |
Example
http://your-server/rest/createPlaylist.view?name=abc&songId=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
Since 1.14.0
A subsonic-response element with a nested playlist element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"playlist": {
"id": "800000075",
"name": "testcreate",
"owner": "user",
"public": true,
"created": "2023-03-16T03:18:41+00:00",
"changed": "2023-03-16T03:18:41+00:00",
"songCount": 1,
"duration": 304,
"entry": [
{
"id": "300000060",
"parent": "200000002",
"title": "BrownSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000060",
"duration": 304,
"bitRate": 20,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 5,
"averageRating": 5,
"track": 4,
"year": 2007,
"genre": "Electronic",
"size": 792375,
"discNumber": 1,
"suffix": "wma",
"contentType": "audio/x-ms-wma",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"playlist": {
"id": "800000075",
"name": "testcreate",
"owner": "user",
"public": true,
"created": "2023-03-16T03:18:41+00:00",
"changed": "2023-03-16T03:18:41+00:00",
"songCount": 1,
"duration": 304,
"entry": [
{
"id": "300000060",
"parent": "200000002",
"title": "BrownSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000060",
"duration": 304,
"bitRate": 20,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 5,
"averageRating": 5,
"track": 4,
"year": 2007,
"genre": "Electronic",
"size": 792375,
"discNumber": 1,
"suffix": "wma",
"contentType": "audio/x-ms-wma",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
playlist |
playlist |
Yes | The created playlist |
Before 1.14.0
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}6 - createPodcastChannel
Adds a new Podcast channel.
http://your-server/rest/createPodcastChannel 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).
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
url |
Yes | The URL of the Podcast to add. |
Example
http://your-server/rest/createPodcastChannel.view?url=url&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}7 - createShare
Creates a public URL that can be used by anyone to stream music or video from the server.
http://your-server/rest/createShare Since 1.6.0
Creates a public URL that can be used by anyone to stream music or video from the 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).
Parameters
| Parameter | Req. | OpenS. | 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. |
Example
http://your-server/rest/createShare.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested shares element on success. Which in turns contains a single share element for the newly created share
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"shares": {
"share": [
{
"id": "12",
"url": "http://localhost:8989/share.php?id=12&secret=fXlKyEv3",
"description": "Forget and Remember (Comfort Fit)",
"username": "user",
"created": "2023-03-16T04:13:09+00:00",
"visitCount": 0,
"entry": [
{
"id": "300000116",
"parent": "200000021",
"title": "Can I Help U?",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000021",
"album": "Forget and Remember",
"artistId": "100000036",
"artist": "Comfort Fit",
"coverArt": "300000116",
"duration": 103,
"bitRate": 216,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 1,
"year": 2005,
"genre": "Hip-Hop",
"size": 2811819,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
},
{
"id": "300000121",
"parent": "200000021",
"title": "Planetary Picknick",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000021",
"album": "Forget and Remember",
"artistId": "100000036",
"artist": "Comfort Fit",
"coverArt": "300000121",
"duration": 358,
"bitRate": 238,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 2,
"year": 2005,
"genre": "Hip-Hop",
"size": 10715592,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
}
]
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"shares": {
"share": [
{
"id": "12",
"url": "http://localhost:8989/share.php?id=12&secret=fXlKyEv3",
"description": "Forget and Remember (Comfort Fit)",
"username": "user",
"created": "2023-03-16T04:13:09+00:00",
"visitCount": 0,
"entry": [
{
"id": "300000116",
"parent": "200000021",
"title": "Can I Help U?",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000021",
"album": "Forget and Remember",
"artistId": "100000036",
"artist": "Comfort Fit",
"coverArt": "300000116",
"duration": 103,
"bitRate": 216,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 1,
"year": 2005,
"genre": "Hip-Hop",
"size": 2811819,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
},
{
"id": "300000121",
"parent": "200000021",
"title": "Planetary Picknick",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000021",
"album": "Forget and Remember",
"artistId": "100000036",
"artist": "Comfort Fit",
"coverArt": "300000121",
"duration": 358,
"bitRate": 238,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 2,
"year": 2005,
"genre": "Hip-Hop",
"size": 10715592,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
}
]
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
shares |
shares |
Yes | The created share |
8 - createUser
Creates a new user on the server.
http://your-server/rest/createUser Since 1.1.0
Creates a new user on the server, using the following parameters:
Parameters
| Parameter | Req. | OpenS. | 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 personal 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. Since 1.8.0, changing this role has no effect. | |
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. | |
videoConversionRole |
No | false | (Since 1.15.0) Whether the user is allowed to start video conversions. | |
musicFolderId |
No | All folders | (Since 1.12.0) IDs of the music folders the user is allowed access to. Include the parameter once for each folder. |
Example
http://your-server/rest/createUser.view?username=test&password=test&email=test@test.com&name=radio&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}9 - deleteBookmark
Creates or updates a bookmark.
http://your-server/rest/deleteBookmark Since 1.9.0
Creates or updates a bookmark (a position within a media file). Bookmarks are personal and not visible to other users.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | ID of the media file for which to delete the bookmark. Other users’ bookmarks are not affected. |
Example
http://your-server/rest/deleteBookmark.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}10 - deleteInternetRadioStation
Deletes an existing internet radio station.
http://your-server/rest/deleteInternetRadioStation Since 1.16.0
Deletes an existing internet radio station. Only users with admin privileges are allowed to call this method.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The ID for the station. |
Example
http://your-server/rest/deleteInternetRadioStation.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}11 - deletePlaylist
Deletes a saved playlist.
http://your-server/rest/deletePlaylist Since 1.2.0
Deletes a saved playlist.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | ID of the playlist to delete, as obtained by getPlaylists. |
Example
http://your-server/rest/deletePlaylist.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}12 - deletePodcastChannel
Deletes a Podcast channel.
http://your-server/rest/deletePodcastChannel 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).
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The ID of the Podcast channel to delete. |
Example
http://your-server/rest/deletePodcastChannel.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status":"ok",
"version":"1.16.1",
}
}13 - deletePodcastEpisode
Deletes a Podcast episode.
http://your-server/rest/deletePodcastEpisode 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).
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The ID of the Podcast episode to delete. |
Example
http://your-server/rest/deletePodcastEpisode.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}14 - deleteShare
Deletes an existing share.
http://your-server/rest/deleteShare Since 1.6.0
Deletes an existing share.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | ID of the share to delete. |
Example
http://your-server/rest/deleteShare.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}15 - deleteUser
Deletes an existing user on the server.
http://your-server/rest/deleteUser Since 1.3.0
Deletes an existing user on the server, using the following parameters:
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
username |
Yes | The name of the user to delete. |
Example
http://your-server/rest/deleteUser.view?username=test&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}16 - download
Downloads a given media file.
http://your-server/rest/download Since 1.0.0
Downloads a given media file. Similar to stream, but this method returns the original media data without transcoding or downsampling.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | A string which uniquely identifies the file to stream. Obtained by calls to getMusicDirectory. |
Example
http://your-server/rest/download.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
Returns binary data on success, or an XML document on error (in which case the HTTP content type will start with “text/xml”).
17 - downloadPodcastEpisode
Request the server to start downloading a given Podcast episode.
http://your-server/rest/downloadPodcastEpisode 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).
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The ID of the Podcast episode to download. |
Example
http://your-server/rest/downloadPodcastEpisode.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}18 - getAlbum
Returns details for an album.
http://your-server/rest/getAlbum Since 1.8.0
Returns details for an album, including a list of songs. This method organizes music according to ID3 tags.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The album ID. |
Example
http://your-server/rest/getAlbum.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested album element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"album": {
"id": "200000021",
"parent": "100000036",
"album": "Forget and Remember",
"title": "Forget and Remember",
"name": "Forget and Remember",
"isDir": true,
"coverArt": "al-200000021",
"songCount": 20,
"created": "2021-07-22T02:09:31+00:00",
"duration": 4248,
"playCount": 0,
"artistId": "100000036",
"artist": "Comfort Fit",
"year": 2005,
"genre": "Hip-Hop",
"song": [
{
"id": "300000116",
"parent": "200000021",
"title": "Can I Help U?",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000021",
"album": "Forget and Remember",
"artistId": "100000036",
"artist": "Comfort Fit",
"coverArt": "300000116",
"duration": 103,
"bitRate": 216,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 1,
"year": 2005,
"genre": "Hip-Hop",
"size": 2811819,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
},
{
"id": "300000121",
"parent": "200000021",
"title": "Planetary Picknick",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000021",
"album": "Forget and Remember",
"artistId": "100000036",
"artist": "Comfort Fit",
"coverArt": "300000121",
"duration": 358,
"bitRate": 238,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 2,
"year": 2005,
"genre": "Hip-Hop",
"size": 10715592,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"album": {
"id": "200000021",
"parent": "100000036",
"album": "Forget and Remember",
"title": "Forget and Remember",
"name": "Forget and Remember",
"isDir": true,
"coverArt": "al-200000021",
"songCount": 20,
"created": "2021-07-22T02:09:31+00:00",
"duration": 4248,
"playCount": 0,
"artistId": "100000036",
"artist": "Comfort Fit",
"year": 2005,
"genre": "Hip-Hop",
"song": [
{
"id": "300000116",
"parent": "200000021",
"title": "Can I Help U?",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000021",
"album": "Forget and Remember",
"artistId": "100000036",
"artist": "Comfort Fit",
"coverArt": "300000116",
"duration": 103,
"bitRate": 216,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 1,
"year": 2005,
"genre": "Hip-Hop",
"size": 2811819,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
},
{
"id": "300000121",
"parent": "200000021",
"title": "Planetary Picknick",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000021",
"album": "Forget and Remember",
"artistId": "100000036",
"artist": "Comfort Fit",
"coverArt": "300000121",
"duration": 358,
"bitRate": 238,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 2,
"year": 2005,
"genre": "Hip-Hop",
"size": 10715592,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
album |
album |
Yes | The album |
19 - getAlbumInfo
Returns album info.
http://your-server/rest/getAlbumInfo Since 1.14.0
Returns album notes, image URLs etc, using data from last.fm.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The album ID or song ID. |
Example
http://your-server/rest/getAlbumInfo.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested albumInfo element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"albumInfo": {
"notes": "Download the full release here (creative commons). These cripsy beats are ripe with thumping funk and techno influences, sample wizardry and daring shuffles. Composed with the help of unique sound plugins which were especially programmed to measure Comfort Fit’s needs and wishes, we think the chances aren’t bad that you’ll fall for the unique sound signature, bounce and elegance of this unusual Hip Hop production. Ltj bukem / Good looking Rec., UK: \"Really love this music.\" Velanche / XLR8R, UK: \"Awesome job he's done... overall production is dope.\" Kwesi / BBE Music, UK: \"Wooooooowwwww... WHAT THE FUCK! THIS IS WHAT",
"musicBrainzId": "6e1d48f7-717c-416e-af35-5d2454a13af2",
"smallImageUrl": "http://localhost:8989/play/art/0f8c3cbd6b0b22c3b5402141351ac812/album/21/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/41b16680dc1b3aaf5dfba24ddb6a1712/album/21/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e6fd8d4e0d35c4436e56991892bfb27b/album/21/thumb174.jpg"
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"albumInfo": {
"notes": "Download the full release here (creative commons). These cripsy beats are ripe with thumping funk and techno influences, sample wizardry and daring shuffles. Composed with the help of unique sound plugins which were especially programmed to measure Comfort Fit’s needs and wishes, we think the chances aren’t bad that you’ll fall for the unique sound signature, bounce and elegance of this unusual Hip Hop production. Ltj bukem / Good looking Rec., UK: \"Really love this music.\" Velanche / XLR8R, UK: \"Awesome job he's done... overall production is dope.\" Kwesi / BBE Music, UK: \"Wooooooowwwww... WHAT THE FUCK! THIS IS WHAT",
"musicBrainzId": "6e1d48f7-717c-416e-af35-5d2454a13af2",
"smallImageUrl": "http://localhost:8989/play/art/0f8c3cbd6b0b22c3b5402141351ac812/album/21/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/41b16680dc1b3aaf5dfba24ddb6a1712/album/21/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e6fd8d4e0d35c4436e56991892bfb27b/album/21/thumb174.jpg"
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
albumInfo |
albumInfo |
Yes | The album info |
20 - getAlbumInfo2
Returns album info.
http://your-server/rest/getAlbumInfo2 Since 1.14.0
Similar to getAlbumInfo, but organizes music according to ID3 tags.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The album ID or song ID. |
Example
http://your-server/rest/getAlbumInfo2.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested albumInfo element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"albumInfo": {
"notes": "Download the full release here (creative commons). These cripsy beats are ripe with thumping funk and techno influences, sample wizardry and daring shuffles. Composed with the help of unique sound plugins which were especially programmed to measure Comfort Fit’s needs and wishes, we think the chances aren’t bad that you’ll fall for the unique sound signature, bounce and elegance of this unusual Hip Hop production. Ltj bukem / Good looking Rec., UK: \"Really love this music.\" Velanche / XLR8R, UK: \"Awesome job he's done... overall production is dope.\" Kwesi / BBE Music, UK: \"Wooooooowwwww... WHAT THE FUCK! THIS IS WHAT",
"musicBrainzId": "6e1d48f7-717c-416e-af35-5d2454a13af2",
"smallImageUrl": "http://localhost:8989/play/art/0f8c3cbd6b0b22c3b5402141351ac812/album/21/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/41b16680dc1b3aaf5dfba24ddb6a1712/album/21/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e6fd8d4e0d35c4436e56991892bfb27b/album/21/thumb174.jpg"
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"albumInfo": {
"notes": "Download the full release here (creative commons). These cripsy beats are ripe with thumping funk and techno influences, sample wizardry and daring shuffles. Composed with the help of unique sound plugins which were especially programmed to measure Comfort Fit’s needs and wishes, we think the chances aren’t bad that you’ll fall for the unique sound signature, bounce and elegance of this unusual Hip Hop production. Ltj bukem / Good looking Rec., UK: \"Really love this music.\" Velanche / XLR8R, UK: \"Awesome job he's done... overall production is dope.\" Kwesi / BBE Music, UK: \"Wooooooowwwww... WHAT THE FUCK! THIS IS WHAT",
"musicBrainzId": "6e1d48f7-717c-416e-af35-5d2454a13af2",
"smallImageUrl": "http://localhost:8989/play/art/0f8c3cbd6b0b22c3b5402141351ac812/album/21/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/41b16680dc1b3aaf5dfba24ddb6a1712/album/21/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e6fd8d4e0d35c4436e56991892bfb27b/album/21/thumb174.jpg"
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
albumInfo |
albumInfo |
Yes | The album info |
21 - getAlbumList
Returns a list of random, newest, highest rated etc. albums.
http://your-server/rest/getAlbumList 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.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
type |
Yes | The list type. Must be one of the following: random, newest, highest, frequent, recent. Since 1.8.0 you can also use 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”. | ||
musicFolderId |
No | (Since 1.11.0) Only return albums in the music folder with the given ID. See getMusicFolders. |
Example
http://your-server/rest/getAlbumList.view?type=random&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested albumList element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"albumList": {
"album": [
{
"id": "200000021",
"parent": "100000036",
"album": "Forget and Remember",
"title": "Forget and Remember",
"name": "Forget and Remember",
"isDir": true,
"coverArt": "al-200000021",
"songCount": 20,
"created": "2021-07-22T02:09:31+00:00",
"duration": 4248,
"playCount": 0,
"artistId": "100000036",
"artist": "Comfort Fit",
"year": 2005,
"genre": "Hip-Hop"
},
{
"id": "200000012",
"parent": "100000019",
"album": "Buried in Nausea",
"title": "Buried in Nausea",
"name": "Buried in Nausea",
"isDir": true,
"coverArt": "al-200000012",
"songCount": 9,
"created": "2021-02-24T01:44:21+00:00",
"duration": 1879,
"playCount": 0,
"artistId": "100000019",
"artist": "Various Artists",
"year": 2012,
"genre": "Punk"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"albumList": {
"album": [
{
"id": "200000021",
"parent": "100000036",
"album": "Forget and Remember",
"title": "Forget and Remember",
"name": "Forget and Remember",
"isDir": true,
"coverArt": "al-200000021",
"created": "2021-07-22T02:09:31+00:00",
"duration": 4248,
"playCount": 0,
"artistId": "100000036",
"artist": "Comfort Fit",
"year": 2005,
"genre": "Hip-Hop"
},
{
"id": "200000012",
"parent": "100000019",
"album": "Buried in Nausea",
"title": "Buried in Nausea",
"name": "Buried in Nausea",
"isDir": true,
"coverArt": "al-200000012",
"created": "2021-02-24T01:44:21+00:00",
"duration": 1879,
"playCount": 0,
"artistId": "100000019",
"artist": "Various Artists",
"year": 2012,
"genre": "Punk"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
albumList |
albumList |
Yes | The album list |
22 - getAlbumList2
Returns a list of random, newest, highest rated etc. albums.
http://your-server/rest/getAlbumList2 Since 1.8.0
Similar to getAlbumList, but organizes music according to ID3 tags.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
type |
Yes | The list type. Must be one of the following: random, newest, highest, frequent, recent. Since 1.8.0 you can also use 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”. | ||
musicFolderId |
No | (Since 1.11.0) Only return albums in the music folder with the given ID. See getMusicFolders. |
Example
http://your-server/rest/getAlbumList2.view?type=random&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested albumList2 element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"albumList2": {
"album": [
{
"id": "200000021",
"album": "Forget and Remember",
"title": "Forget and Remember",
"name": "Forget and Remember",
"coverArt": "al-200000021",
"songCount": 20,
"created": "2021-07-22T02:09:31+00:00",
"duration": 4248,
"playCount": 0,
"artistId": "100000036",
"artist": "Comfort Fit",
"year": 2005,
"genre": "Hip-Hop"
},
{
"id": "200000012",
"album": "Buried in Nausea",
"title": "Buried in Nausea",
"name": "Buried in Nausea",
"coverArt": "al-200000012",
"songCount": 9,
"created": "2021-02-24T01:44:21+00:00",
"duration": 1879,
"playCount": 0,
"artistId": "100000019",
"artist": "Various Artists",
"year": 2012,
"genre": "Punk"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"albumList2": {
"album": [
{
"id": "200000021",
"album": "Forget and Remember",
"title": "Forget and Remember",
"name": "Forget and Remember",
"coverArt": "al-200000021",
"songCount": 20,
"created": "2021-07-22T02:09:31+00:00",
"duration": 4248,
"playCount": 0,
"artistId": "100000036",
"artist": "Comfort Fit",
"year": 2005,
"genre": "Hip-Hop"
},
{
"id": "200000012",
"album": "Buried in Nausea",
"title": "Buried in Nausea",
"name": "Buried in Nausea",
"coverArt": "al-200000012",
"songCount": 9,
"created": "2021-02-24T01:44:21+00:00",
"duration": 1879,
"playCount": 0,
"artistId": "100000019",
"artist": "Various Artists",
"year": 2012,
"genre": "Punk"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
albumList2 |
albumList2 |
Yes | The album list |
23 - getArtist
Returns details for an artist.
http://your-server/rest/getArtist Since 1.8.0
Returns details for an artist, including a list of albums. This method organizes music according to ID3 tags.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The artist ID. |
Example
http://your-server/rest/getArtist.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested artist element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"artist": {
"id": "100000002",
"name": "Synthetic",
"coverArt": "ar-100000002",
"albumCount": 1,
"starred": "2021-02-22T05:54:18Z",
"album": [
{
"id": "200000002",
"parent": "100000002",
"album": "Colorsmoke EP",
"title": "Colorsmoke EP",
"name": "Colorsmoke EP",
"isDir": true,
"coverArt": "al-200000002",
"songCount": 12,
"created": "2021-02-23T04:24:48+00:00",
"duration": 4568,
"playCount": 1,
"artistId": "100000002",
"artist": "Synthetic",
"year": 2007,
"genre": "Electronic",
"userRating": 5,
"averageRating": 3,
"starred": "2021-02-22T05:51:53Z"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"artist": {
"id": "100000002",
"name": "Synthetic",
"coverArt": "ar-100000002",
"albumCount": 1,
"starred": "2021-02-22T05:54:18Z",
"album": [
{
"id": "200000002",
"parent": "100000002",
"album": "Colorsmoke EP",
"title": "Colorsmoke EP",
"name": "Colorsmoke EP",
"isDir": true,
"coverArt": "al-200000002",
"songCount": 12,
"created": "2021-02-23T04:24:48+00:00",
"duration": 4568,
"playCount": 1,
"artistId": "100000002",
"artist": "Synthetic",
"year": 2007,
"genre": "Electronic",
"userRating": 5,
"averageRating": 3,
"starred": "2021-02-22T05:51:53Z"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
artist |
artist |
Yes | The artist |
24 - getArtistInfo
Returns artist info.
http://your-server/rest/getArtistInfo Since 1.11.0
Returns artist info with biography, image URLs and similar artists, using data from last.fm.
Parameters
| Parameter | Req. | OpenS. | 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. |
Example
http://your-server/rest/getArtistInfo.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested artistInfo element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"artistInfo": {
"biography": {},
"musicBrainzId": "1",
"smallImageUrl": "http://localhost:8989/play/art/f20070e8e11611cc53542a38801d60fa/artist/2/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/2b9b6c057cd4bf21089ce7572e7792b6/artist/2/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e18287c23a75e263b64c31b3d64c1944/artist/2/thumb174.jpg"
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"artistInfo": {
"biography": {},
"musicBrainzId": "1",
"smallImageUrl": "http://localhost:8989/play/art/f20070e8e11611cc53542a38801d60fa/artist/2/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/2b9b6c057cd4bf21089ce7572e7792b6/artist/2/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e18287c23a75e263b64c31b3d64c1944/artist/2/thumb174.jpg"
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
artistInfo |
artistInfo |
Yes | The album info |
25 - getArtistInfo2
Returns artist info.
http://your-server/rest/getArtistInfo2 Since 1.11.0
Similar to getArtistInfo, but organizes music according to ID3 tags.
Parameters
| Parameter | Req. | OpenS. | 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. |
Example
http://your-server/rest/getArtistInfo2.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested artistInfo2 element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"artistInfo2": {
"biography": {},
"musicBrainzId": "1",
"smallImageUrl": "http://localhost:8989/play/art/f20070e8e11611cc53542a38801d60fa/artist/2/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/2b9b6c057cd4bf21089ce7572e7792b6/artist/2/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e18287c23a75e263b64c31b3d64c1944/artist/2/thumb174.jpg"
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"artistInfo2": {
"biography": {},
"musicBrainzId": "1",
"smallImageUrl": "http://localhost:8989/play/art/f20070e8e11611cc53542a38801d60fa/artist/2/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/2b9b6c057cd4bf21089ce7572e7792b6/artist/2/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e18287c23a75e263b64c31b3d64c1944/artist/2/thumb174.jpg"
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
artistInfo2 |
artistInfo2 |
Yes | The album info |
26 - getArtists
Returns all artists.
http://your-server/rest/getArtists Since 1.8.0
Similar to getIndexes, but organizes music according to ID3 tags.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
musicFolderId |
No | If specified, only return artists in the music folder with the given ID. See getMusicFolders. |
Example
http://your-server/rest/getArtists.view?&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested artists element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true,
"artists": {
"ignoredArticles": "The An A Die Das Ein Eine Les Le La",
"index": [
{
"name": "C",
"artist": [
{
"id": "100000016",
"name": "CARNÚN",
"coverArt": "ar-100000016",
"albumCount": 1
},
{
"id": "100000027",
"name": "Chi.Otic",
"coverArt": "ar-100000027",
"albumCount": 0
}
]
},
{
"name": "I",
"artist": [
{
"id": "100000013",
"name": "IOK-1",
"coverArt": "ar-100000013",
"albumCount": 1
}
]
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"artists": {
"ignoredArticles": "The An A Die Das Ein Eine Les Le La",
"index": [
{
"name": "C",
"artist": [
{
"id": "100000016",
"name": "CARNÚN",
"coverArt": "ar-100000016",
"albumCount": 1
},
{
"id": "100000027",
"name": "Chi.Otic",
"coverArt": "ar-100000027",
"albumCount": 0
}
]
},
{
"name": "I",
"artist": [
{
"id": "100000013",
"name": "IOK-1",
"coverArt": "ar-100000013",
"albumCount": 1
}
]
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
artists |
artists |
Yes | The artist list |
27 - getAvatar
Returns the avatar (personal image) for a user.
http://your-server/rest/getAvatar Since 1.8.0
Returns the avatar (personal image) for a user.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
username |
Yes | The user in question.. |
Example
http://your-server/rest/getAvatar.view?username=test&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
Returns the avatar image in binary form on success, or an XML document on error (in which case the HTTP content type will start with “text/xml”).
28 - getBookmarks
Returns all bookmarks for this user.
http://your-server/rest/getBookmarks Since 1.9.0
Returns all bookmarks for this user. A bookmark is a position within a certain media file.
Parameters
Takes no extra parameters.
Example
http://your-server/rest/getBookmarks.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested bookmarks element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"bookmarks": {
"bookmark": [
{
"entry": {
"id": "113bf5989ad15ce2cf1834ba9622983f",
"parent": "b87a936c682c49d4494c7ccb08c22d23",
"isDir": false,
"title": "Stay Out Here",
"album": "Shaking The Habitual",
"artist": "The Knife",
"track": 11,
"year": 2013,
"genre": "Electronic",
"coverArt": "al-b87a936c682c49d4494c7ccb08c22d23_0",
"size": 21096309,
"contentType": "audio/mp4",
"suffix": "m4a",
"duration": 642,
"bitRate": 257,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"path": "The Knife/Shaking The Habitual/11 - Stay Out Here.m4a",
"created": "2023-03-13T16:30:35Z",
"albumId": "b87a936c682c49d4494c7ccb08c22d23",
"artistId": "b29e9a9d780cb0e133f3add5662771b9",
"type": "music",
"isVideo": false,
"bookmarkPosition": 129000
},
"position": 129000,
"username": "demo",
"comment": "",
"created": "2023-03-13T16:30:35Z",
"changed": "2023-03-13T16:30:35Z"
},
{
"entry": {
"id": "2b42782333450d02b177823e729664af",
"parent": "dc8d8889a6fe08d8da7698c7ee1de61c",
"isDir": false,
"title": "Ill with the Skills",
"album": "First Words",
"artist": "The Polish Ambassador",
"track": 17,
"year": 2014,
"coverArt": "mf-2b42782333450d02b177823e729664af_641edeb3",
"size": 6219581,
"contentType": "audio/mpeg",
"suffix": "mp3",
"duration": 255,
"bitRate": 194,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"path": "The Polish Ambassador/First Words/17 - Ill with the Skills.mp3",
"playCount": 1,
"played": "2023-03-15T15:23:37Z",
"created": "2023-03-25T11:44:51Z",
"albumId": "dc8d8889a6fe08d8da7698c7ee1de61c",
"artistId": "64e1f796b283545d329cdf6a31a31dbe",
"type": "music",
"isVideo": false,
"bookmarkPosition": 7000
},
"position": 7000,
"username": "demo",
"comment": "playSub bookmark",
"created": "2023-03-25T11:44:51Z",
"changed": "2023-03-25T11:44:51Z"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"bookmarks": {
"bookmark": [
{
"entry": {
"id": "113bf5989ad15ce2cf1834ba9622983f",
"parent": "b87a936c682c49d4494c7ccb08c22d23",
"isDir": false,
"title": "Stay Out Here",
"album": "Shaking The Habitual",
"artist": "The Knife",
"track": 11,
"year": 2013,
"genre": "Electronic",
"coverArt": "al-b87a936c682c49d4494c7ccb08c22d23_0",
"size": 21096309,
"contentType": "audio/mp4",
"suffix": "m4a",
"duration": 642,
"bitRate": 257,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"path": "The Knife/Shaking The Habitual/11 - Stay Out Here.m4a",
"created": "2023-03-13T16:30:35Z",
"albumId": "b87a936c682c49d4494c7ccb08c22d23",
"artistId": "b29e9a9d780cb0e133f3add5662771b9",
"type": "music",
"isVideo": false,
"bookmarkPosition": 129000
},
"position": 129000,
"username": "demo",
"comment": "",
"created": "2023-03-13T16:30:35Z",
"changed": "2023-03-13T16:30:35Z"
},
{
"entry": {
"id": "2b42782333450d02b177823e729664af",
"parent": "dc8d8889a6fe08d8da7698c7ee1de61c",
"isDir": false,
"title": "Ill with the Skills",
"album": "First Words",
"artist": "The Polish Ambassador",
"track": 17,
"year": 2014,
"coverArt": "mf-2b42782333450d02b177823e729664af_641edeb3",
"size": 6219581,
"contentType": "audio/mpeg",
"suffix": "mp3",
"duration": 255,
"bitRate": 194,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"path": "The Polish Ambassador/First Words/17 - Ill with the Skills.mp3",
"playCount": 1,
"played": "2023-03-15T15:23:37Z",
"created": "2023-03-25T11:44:51Z",
"albumId": "dc8d8889a6fe08d8da7698c7ee1de61c",
"artistId": "64e1f796b283545d329cdf6a31a31dbe",
"type": "music",
"isVideo": false,
"bookmarkPosition": 7000
},
"position": 7000,
"username": "demo",
"comment": "playSub bookmark",
"created": "2023-03-25T11:44:51Z",
"changed": "2023-03-25T11:44:51Z"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
bookmarks |
bookmarks |
Yes | The bookmarks |
29 - getCaptions
Returns captions (subtitles) for a video.
http://your-server/rest/getCaptions Since 1.14.0
Returns captions (subtitles) for a video. Use getVideoInfo to get a list of available captions.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The ID of the video. | ||
format |
No | Preferred captions format (“srt” or “vtt”). |
Example
http://your-server/rest/getCaptions.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
Returns the raw video captions.
30 - getChatMessages
Returns the current visible (non-expired) chat messages.
http://your-server/rest/getChatMessages Since 1.2.0
Returns the current visible (non-expired) chat messages.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
since |
No | Only return messages newer than this time (in millis since Jan 1 1970). |
Example
http://your-server/rest/getChatMessages.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested chatMessages element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"chatMessages": {
"chatMessage": [
{
"username": "admin",
"time": 1678935707000,
"message": "Api Script Testing"
},
{
"username": "user",
"time": 1678935699000,
"message": "Api Script Testing"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"chatMessages": {
"chatMessage": [
{
"username": "admin",
"time": 1678935707000,
"message": "Api Script Testing"
},
{
"username": "user",
"time": 1678935699000,
"message": "Api Script Testing"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
chatMessages |
chatMessages |
Yes | The message list |
31 - getCoverArt
Returns a cover art image.
http://your-server/rest/getCoverArt Since 1.0.0
Returns a cover art image.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The coverArt ID. Returned by most entities likes Child or AlbumID3 |
||
size |
No | If specified, scale image to this size. |
Example
http://your-server/rest/getCoverArt.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
Returns binary data on success, or an XML document on error (in which case the HTTP content type will start with “text/xml”).
32 - getGenres
Returns all genres.
http://your-server/rest/getGenres Since 1.9.0
Returns all genres.
Parameters
Takes no extra parameters.
Example
http://your-server/rest/getGenres.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested genres element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"genres": {
"genre": [
{
"songCount": 1,
"albumCount": 1,
"value": "Punk"
},
{
"songCount": 4,
"albumCount": 1,
"value": "Dark Ambient"
},
{
"songCount": 6,
"albumCount": 1,
"value": "Noise"
},
{
"songCount": 11,
"albumCount": 1,
"value": "Electronica"
},
{
"songCount": 11,
"albumCount": 1,
"value": "Dance"
},
{
"songCount": 12,
"albumCount": 1,
"value": "Electronic"
},
{
"songCount": 20,
"albumCount": 1,
"value": "Hip-Hop"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"genres": {
"genre": [
{
"songCount": 1,
"albumCount": 1,
"value": "Punk"
},
{
"songCount": 4,
"albumCount": 1,
"value": "Dark Ambient"
},
{
"songCount": 6,
"albumCount": 1,
"value": "Noise"
},
{
"songCount": 11,
"albumCount": 1,
"value": "Electronica"
},
{
"songCount": 11,
"albumCount": 1,
"value": "Dance"
},
{
"songCount": 12,
"albumCount": 1,
"value": "Electronic"
},
{
"songCount": 20,
"albumCount": 1,
"value": "Hip-Hop"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
genres |
genres |
Yes | The genre list |
33 - getIndexes
Returns an indexed structure of all artists.
http://your-server/rest/getIndexes Since 1.0.0
Returns an indexed structure of all artists.
Parameters
| Parameter | Req. | OpenS. | 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). |
Example
http://your-server/rest/getIndexes.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested indexes element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true,
"indexes": {
"shortcut": [
{
"id": "11",
"name": "Audio books"
},
{
"id": "10",
"name": "Podcasts"
}
],
"index": [
{
"artist": [
{
"id": "1",
"name": "ABBA"
},
{
"id": "2",
"name": "Alanis Morisette"
},
{
"id": "3",
"name": "Alphaville",
"starred": "2013-11-02T12:30:00"
}
],
"name": "A"
},
{
"artist": {
"name": "Bob Dylan",
"id": "4"
},
"name": "B"
}
],
"child": [
{
"id": "111",
"parent": "11",
"title": "Dancing Queen",
"isDir": "false",
"album": "Arrival",
"artist": "ABBA",
"track": "7",
"year": "1978",
"genre": "Pop",
"coverArt": "24",
"size": "8421341",
"contentType": "audio/mpeg",
"suffix": "mp3",
"duration": "146",
"bitRate": "128",
"path": "ABBA/Arrival/Dancing Queen.mp3"
},
{
"id": "112",
"parent": "11",
"title": "Money, Money, Money",
"isDir": "false",
"album": "Arrival",
"artist": "ABBA",
"track": "7",
"year": "1978",
"genre": "Pop",
"coverArt": "25",
"size": "4910028",
"contentType": "audio/flac",
"suffix": "flac",
"transcodedContentType": "audio/mpeg",
"transcodedSuffix": "mp3",
"duration": "208",
"bitRate": "128",
"path": "ABBA/Arrival/Money, Money, Money.mp3"
}
],
"lastModified": "237462836472342",
"ignoredArticles": "The El La Los Las Le Les"
}
}
}<subsonic-response status="ok" version="1.16.1" type="AwesomeServerName" serverVersion="0.1.3 (tag)" openSubsonic="true">
<indexes lastModified="237462836472342" ignoredArticles="The El La Los Las Le Les">
<shortcut id="11" name="Audio books"/>
<shortcut id="10" name="Podcasts"/>
<index name="A">
<artist id="1" name="ABBA"/>
<artist id="2" name="Alanis Morisette"/>
<artist id="3" name="Alphaville" starred="2013-11-02T12:30:00"/>
</index>
<index name="B">
<artist name="Bob Dylan" id="4"/>
</index>
<child id="111" parent="11" title="Dancing Queen" isDir="false" album="Arrival" artist="ABBA" track="7" year="1978" genre="Pop" coverArt="24" size="8421341" contentType="audio/mpeg" suffix="mp3" duration="146" bitRate="128" path="ABBA/Arrival/Dancing Queen.mp3"/>
<child id="112" parent="11" title="Money, Money, Money" isDir="false" album="Arrival" artist="ABBA" track="7" year="1978" genre="Pop" coverArt="25" size="4910028" contentType="audio/flac" suffix="flac" transcodedContentType="audio/mpeg" transcodedSuffix="mp3" duration="208" bitRate="128" path="ABBA/Arrival/Money, Money, Money.mp3"/>
</indexes>
</subsonic-response>{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"indexes": {
"shortcut": [
{
"id": "11",
"name": "Audio books"
},
{
"id": "10",
"name": "Podcasts"
}
],
"index": [
{
"artist": [
{
"id": "1",
"name": "ABBA"
},
{
"id": "2",
"name": "Alanis Morisette"
},
{
"id": "3",
"name": "Alphaville",
"starred": "2013-11-02T12:30:00"
}
],
"name": "A"
},
{
"artist": {
"name": "Bob Dylan",
"id": "4"
},
"name": "B"
}
],
"child": [
{
"id": "111",
"parent": "11",
"title": "Dancing Queen",
"isDir": "false",
"album": "Arrival",
"artist": "ABBA",
"track": "7",
"year": "1978",
"genre": "Pop",
"coverArt": "24",
"size": "8421341",
"contentType": "audio/mpeg",
"suffix": "mp3",
"duration": "146",
"bitRate": "128",
"path": "ABBA/Arrival/Dancing Queen.mp3"
},
{
"id": "112",
"parent": "11",
"title": "Money, Money, Money",
"isDir": "false",
"album": "Arrival",
"artist": "ABBA",
"track": "7",
"year": "1978",
"genre": "Pop",
"coverArt": "25",
"size": "4910028",
"contentType": "audio/flac",
"suffix": "flac",
"transcodedContentType": "audio/mpeg",
"transcodedSuffix": "mp3",
"duration": "208",
"bitRate": "128",
"path": "ABBA/Arrival/Money, Money, Money.mp3"
}
],
"lastModified": "237462836472342",
"ignoredArticles": "The El La Los Las Le Les"
}
}
}<subsonic-response status="ok" version="1.16.1" type="AwesomeServerName">
<indexes lastModified="237462836472342" ignoredArticles="The El La Los Las Le Les">
<shortcut id="11" name="Audio books"/>
<shortcut id="10" name="Podcasts"/>
<index name="A">
<artist id="1" name="ABBA"/>
<artist id="2" name="Alanis Morisette"/>
<artist id="3" name="Alphaville" starred="2013-11-02T12:30:00"/>
</index>
<index name="B">
<artist name="Bob Dylan" id="4"/>
</index>
<child id="111" parent="11" title="Dancing Queen" isDir="false" album="Arrival" artist="ABBA" track="7" year="1978" genre="Pop" coverArt="24" size="8421341" contentType="audio/mpeg" suffix="mp3" duration="146" bitRate="128" path="ABBA/Arrival/Dancing Queen.mp3"/>
<child id="112" parent="11" title="Money, Money, Money" isDir="false" album="Arrival" artist="ABBA" track="7" year="1978" genre="Pop" coverArt="25" size="4910028" contentType="audio/flac" suffix="flac" transcodedContentType="audio/mpeg" transcodedSuffix="mp3" duration="208" bitRate="128" path="ABBA/Arrival/Money, Money, Money.mp3"/>
</indexes>
</subsonic-response>| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
indexes |
indexes |
Yes | The indexed artist list |
34 - getInternetRadioStations
Returns all internet radio stations.
http://your-server/rest/getInternetRadioStations Since 1.9.0
Returns all internet radio stations. Takes no extra parameters.
Parameters
Takes no extra parameters.
Example
http://your-server/rest/getInternetRadioStations.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested internetRadioStations element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"internetRadioStations": {
"internetRadioStation": [
{
"id": "1",
"name": "HBR1.com - Dream Factory",
"streamUrl": "http://ubuntu.hbr1.com:19800/ambient.aac",
"homepageUrl": "http://www.hbr1.com/"
},
{
"id": "2",
"name": "HBR1.com - I.D.M. Tranceponder",
"streamUrl": "http://ubuntu.hbr1.com:19800/trance.ogg",
"homepageUrl": "http://www.hbr1.com/"
},
{
"id": "3",
"name": "4ZZZ Community Radio",
"streamUrl": "https://stream.4zzz.org.au:9200/4zzz",
"homepageUrl": "https://4zzzfm.org.au"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"internetRadioStations": {
"internetRadioStation": [
{
"id": "1",
"name": "HBR1.com - Dream Factory",
"streamUrl": "http://ubuntu.hbr1.com:19800/ambient.aac",
"homepageUrl": "http://www.hbr1.com/"
},
{
"id": "2",
"name": "HBR1.com - I.D.M. Tranceponder",
"streamUrl": "http://ubuntu.hbr1.com:19800/trance.ogg",
"homepageUrl": "http://www.hbr1.com/"
},
{
"id": "3",
"name": "4ZZZ Community Radio",
"streamUrl": "https://stream.4zzz.org.au:9200/4zzz",
"homepageUrl": "https://4zzzfm.org.au"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
internetRadioStations |
internetRadioStations |
Yes | The radio stations |
35 - getLicense
Get details about the software license.
http://your-server/rest/getLicense Since 1.0.0
Get details about the software license.
Parameters
Takes no extra parameters.
Example
http://your-server/rest/getLicense.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested license element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"license": {
"valid": true,
"email": "demo@demo.org",
"licenseExpires": "2017-04-11T10:42:50.842Z",
"trialExpires": "2017-04-11T10:42:50.842Z"
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"license": {
"valid": true,
"email": "demo@demo.org",
"licenseExpires": "2017-04-11T10:42:50.842Z",
"trialExpires": "2017-04-11T10:42:50.842Z"
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
license |
license |
Yes | The status of the license |
36 - getLyrics
Searches for and returns lyrics for a given song.
http://your-server/rest/getLyrics Since 1.2.0
Searches for and returns lyrics for a given song.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
artist |
No | The artist name. | ||
title |
No | The song title. |
Example
http://your-server/rest/getLyrics.view?artist=toto&title=tata&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested lyrics element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"lyrics": {
"artist": "Metallica",
"title": "Blitzkrieg",
"value": "Let us have peace, let us have life\n\nLet us escape the cruel night\n\nLet us have time, let the sun shine\n\nLet us beware the deadly sign\n\n\n\nThe day is coming\n\nArmageddon's near\n\nInferno's coming\n\nCan we survive the blitzkrieg?\n\nThe blitzkrieg\n\nThe blitzkrieg\n\n\n\nSave us from fate, save us from hate\n\nSave ourselves before it's too late\n\nCome to our need, hear our plea\n\nSave ourselves before the earth bleeds\n\n\n\nThe day is dawning\n\nThe time is near\n\nAliens calling\n\nCan we survive the blitzkrieg?"
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"lyrics": {
"artist": "Metallica",
"title": "Blitzkrieg",
"value": "Let us have peace, let us have life\n\nLet us escape the cruel night\n\nLet us have time, let the sun shine\n\nLet us beware the deadly sign\n\n\n\nThe day is coming\n\nArmageddon's near\n\nInferno's coming\n\nCan we survive the blitzkrieg?\n\nThe blitzkrieg\n\nThe blitzkrieg\n\n\n\nSave us from fate, save us from hate\n\nSave ourselves before it's too late\n\nCome to our need, hear our plea\n\nSave ourselves before the earth bleeds\n\n\n\nThe day is dawning\n\nThe time is near\n\nAliens calling\n\nCan we survive the blitzkrieg?"
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
lyrics |
lyrics |
Yes | The lyrics |
37 - getLyricsBySongId
Add support for synchronized lyrics, multiple languages, and retrieval by song ID
OpenSubsonic version: 1
OpenSubsonic extension name songLyrics (As returned by getOpenSubsonicExtensions)
Retrieves all structured lyrics from the server for a given song.
The lyrics can come from embedded tags (SYLT/USLT), LRC file/text file, or any other external source.
http://your-server/rest/getLyricsBySongId
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | Yes | The track ID. |
Special notes about the lang field
Ideally, the server will return lang as an ISO 639 (2/3) code.
However, tagged files and external lyrics can come with any value as a potential language code, so clients should take care when displaying lang.
Furthermore, there is special behavior for the value xxx.
While not an ISO code, it is commonly used by taggers and other parsing software.
Clients should treat xxx as not having a specified language (equivalent to the und code).
Example
http://your-server/rest/getLyricsBySongId.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested lyricsList
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true,
"lyricsList": {
"structuredLyrics": [
{
"displayArtist": "Muse",
"displayTitle": "Hysteria",
"lang": "eng",
"offset": -100,
"synced": true,
"line": [
{
"start": 0,
"value": "It's bugging me"
},
{
"start": 2000,
"value": "Grating me"
},
{
"start": 3001,
"value": "And twisting me around..."
}
]
},
{
"displayArtist": "Muse",
"displayTitle": "Hysteria",
"lang": "und",
"offset": 100,
"synced": false,
"line": [
{
"value": "It's bugging me"
},
{
"value": "Grating me"
},
{
"value": "And twisting me around..."
}
]
}
]
}
}
}<subsonic-response status="ok" version="1.16.1" type="AwesomeServerName" serverVersion="0.1.3 (tag)" openSubsonic="true">
<lyricsList>
<structuredLyrics displayArtist="Muse" displayTitle="Hysteria" lang="en" offset="-100" synced="true">
<line start="0">It's bugging me</line>
<line start="2000">Grating me</line>
<line start="3001">And twisting me around...</line>
</structuredLyrics>
<structuredLyrics displayArtist="Muse" displayTitle="Hysteria" lang="en" offset="100" synced="false">
<line>It's bugging me</line>
<line>Grating me</line>
<line>And twisting me around...</line>
</structuredLyrics>
</lyricsList>
</subsonic-response>Does not exist.| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
lyricsList |
lyricsList |
Yes | Yes | List of structured lyrics |
38 - getMusicDirectory
Returns a listing of all files in a music directory.
http://your-server/rest/getMusicDirectory 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.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | A string which uniquely identifies the music folder. Obtained by calls to getIndexes or getMusicDirectory. |
Example
http://your-server/rest/getMusicDirectory.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested directory element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"directory": {
"id": "1",
"name": "music",
"child": [
{
"id": "100000016",
"parent": "1",
"isDir": true,
"title": "CARNÚN",
"artist": "CARNÚN",
"coverArt": "ar-100000016"
},
{
"id": "100000027",
"parent": "1",
"isDir": true,
"title": "Chi.Otic",
"artist": "Chi.Otic",
"coverArt": "ar-100000027"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"directory": {
"id": "1",
"name": "music",
"child": [
{
"id": "100000016",
"parent": "1",
"isDir": true,
"title": "CARNÚN",
"artist": "CARNÚN",
"coverArt": "ar-100000016"
},
{
"id": "100000027",
"parent": "1",
"isDir": true,
"title": "Chi.Otic",
"artist": "Chi.Otic",
"coverArt": "ar-100000027"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
directory |
directory |
Yes | The directory content |
39 - getMusicFolders
Returns all configured top-level music folders.
http://your-server/rest/getMusicFolders Since 1.0.0
Returns all configured top-level music folders. Takes no extra parameters.
Parameters
Takes no extra parameters.
Example
http://your-server/rest/getMusicFolders.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested musicFolders element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"musicFolders": {
"musicFolder": [
{
"id": "1",
"name": "music"
},
{
"id": "4",
"name": "upload"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"musicFolders": {
"musicFolder": [
{
"id": "1",
"name": "music"
},
{
"id": "4",
"name": "upload"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
musicFolders |
musicFolders |
Yes | The directory content |
40 - getNewestPodcasts
Returns the most recently published Podcast episodes.
http://your-server/rest/getNewestPodcasts Since 1.13.0
Returns the most recently published Podcast episodes.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
count |
No | 20 | The maximum number of episodes to return. |
Example
http://your-server/rest/getNewestPodcasts.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested newestPodcasts element on success.
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
newestPodcasts |
newestPodcasts |
Yes | The podacsts |
41 - getNowPlaying
Returns what is currently being played by all users.
http://your-server/rest/getNowPlaying Since 1.0.0
Returns what is currently being played by all users. Takes no extra parameters.
Parameters
Takes no extra parameters.
Example
http://your-server/rest/getNowPlaying.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested nowPlaying element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"nowPlaying": {
"entry": [
{
"id": "300115266",
"parent": "200147046",
"title": "Take the Home",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200147046",
"album": "How I Learned to Love Our Robot Overlords",
"artistId": "100002619",
"artist": "Raggedy Angry",
"coverArt": "300115266",
"duration": 227,
"bitRate": 222,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 3,
"track": 7,
"year": 2010,
"genre": "Industrial",
"size": 6341039,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "Raggedy Angry/(2010) How I Learned to Love Our Robot Overlords/1-07 - Take the Home.mp3",
"username": "user",
"minutesAgo": 0,
"playerId": 0
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"nowPlaying": {
"entry": [
{
"id": "300115266",
"parent": "200147046",
"title": "Take the Home",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200147046",
"album": "How I Learned to Love Our Robot Overlords",
"artistId": "100002619",
"artist": "Raggedy Angry",
"coverArt": "300115266",
"duration": 227,
"bitRate": 222,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 3,
"track": 7,
"year": 2010,
"genre": "Industrial",
"size": 6341039,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "Raggedy Angry/(2010) How I Learned to Love Our Robot Overlords/1-07 - Take the Home.mp3",
"username": "user",
"minutesAgo": 0,
"playerId": 0
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
nowPlaying |
nowPlaying |
Yes | The now playing content |
42 - getOpenSubsonicExtensions
List the OpenSubsonic extensions supported by this server.
http://your-server/rest/getOpenSubsonicExtensions OpenSubsonic version 1
List the OpenSubsonic extensions supported by this server.
Parameters
Takes no extra parameters.
Note: Unlike all other APIs getOpenSubsonicExtensions must be publicly accessible.
Example
http://your-server/rest/getOpenSubsonicExtensions.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested openSubsonicExtensions element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true,
"openSubsonicExtensions": [
{
"name": "template",
"versions": [
1,
2
]
},
{
"name": "transcodeOffset",
"versions": [
1
]
}
]
}
}Does not exist.| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
openSubsonicExtensions |
An array of openSubsonicExtension |
Yes | The list of supported extensions |
OpenSubsonic
This is a new endpoint.43 - getPlaylist
Returns a listing of files in a saved playlist.
http://your-server/rest/getPlaylist Since 1.0.0
Returns a listing of files in a saved playlist.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
yes | ID of the playlist to return, as obtained by getPlaylists. |
Example
http://your-server/rest/getPlaylist.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested playlist element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"playlist": {
"id": "800000075",
"name": "testcreate",
"owner": "user",
"public": true,
"created": "2023-03-16T03:18:41+00:00",
"changed": "2023-03-16T03:18:41+00:00",
"songCount": 1,
"duration": 304,
"entry": [
{
"id": "300000060",
"parent": "200000002",
"title": "BrownSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000060",
"duration": 304,
"bitRate": 20,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 5,
"averageRating": 5,
"track": 4,
"year": 2007,
"genre": "Electronic",
"size": 792375,
"discNumber": 1,
"suffix": "wma",
"contentType": "audio/x-ms-wma",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"playlist": {
"id": "800000075",
"name": "testcreate",
"owner": "user",
"public": true,
"created": "2023-03-16T03:18:41+00:00",
"changed": "2023-03-16T03:18:41+00:00",
"songCount": 1,
"duration": 304,
"entry": [
{
"id": "300000060",
"parent": "200000002",
"title": "BrownSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000060",
"duration": 304,
"bitRate": 20,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 5,
"averageRating": 5,
"track": 4,
"year": 2007,
"genre": "Electronic",
"size": 792375,
"discNumber": 1,
"suffix": "wma",
"contentType": "audio/x-ms-wma",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
playlist |
playlist |
Yes | The created playlist |
44 - getPlaylists
Returns all playlists a user is allowed to play.
http://your-server/rest/getPlaylists Since 1.0.0
Returns all playlists a user is allowed to play.
Parameters
| Parameter | Req. | OpenS. | 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. |
Example
http://your-server/rest/getPlaylists.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested playlists element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"playlists": {
"playlist": [
{
"id": "800000003",
"name": "random - admin - private (admin)",
"owner": "admin",
"public": false,
"created": "2021-02-23T04:35:38+00:00",
"changed": "2021-02-23T04:35:38+00:00",
"songCount": 43,
"duration": 17875
},
{
"id": "800000002",
"name": "random - admin - public (admin)",
"owner": "admin",
"public": true,
"created": "2021-02-23T04:34:56+00:00",
"changed": "2021-02-23T04:34:56+00:00",
"songCount": 43,
"duration": 17786
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"playlists": {
"playlist": [
{
"id": "800000003",
"name": "random - admin - private (admin)",
"owner": "admin",
"public": false,
"created": "2021-02-23T04:35:38+00:00",
"changed": "2021-02-23T04:35:38+00:00",
"songCount": 43,
"duration": 17875
},
{
"id": "800000002",
"name": "random - admin - public (admin)",
"owner": "admin",
"public": true,
"created": "2021-02-23T04:34:56+00:00",
"changed": "2021-02-23T04:34:56+00:00",
"songCount": 43,
"duration": 17786
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
playlists |
playlists |
Yes | The playlists |
45 - getPlayQueue
Returns the state of the play queue for this user.
http://your-server/rest/getPlayQueue Since 1.12.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).
Parameters
Takes no extra parameters.
Example
http://your-server/rest/getPlayQueue.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested playQueue element on success.
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
playQueue |
playQueue |
Yes | The play queue |
46 - getPodcasts
Returns all Podcast channels the server subscribes to, and (optionally) their episodes.
http://your-server/rest/getPodcasts Since 1.6.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.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
includeEpisodes |
No | true | (Since 1.9.0) Whether to include Podcast episodes in the returned result. | |
id |
No | (Since 1.9.0) If specified, only return the Podcast channel with this ID. |
Example
http://your-server/rest/getPodcasts.view?title=tata&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested podcasts element on success.
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
podcasts |
podcasts |
Yes | The podacsts |
47 - getRandomSongs
Returns random songs matching the given criteria.
http://your-server/rest/getRandomSongs Since 1.2.0
Returns random songs matching the given criteria.
Parameters
| Parameter | Req. | OpenS. | 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. |
Example
http://your-server/rest/getRandomSongs.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested randomSongs element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"randomSongs": {
"song": [
{
"id": "300000060",
"parent": "200000002",
"title": "BrownSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000060",
"duration": 304,
"bitRate": 20,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 5,
"averageRating": 5,
"track": 4,
"year": 2007,
"genre": "Electronic",
"size": 792375,
"discNumber": 1,
"suffix": "wma",
"contentType": "audio/x-ms-wma",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
},
{
"id": "300000055",
"parent": "200000002",
"title": "Red&GreenSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000055",
"duration": 400,
"bitRate": 64,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 5,
"year": 2007,
"genre": "Electronic",
"size": 3209886,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"randomSongs": {
"song": [
{
"id": "300000060",
"parent": "200000002",
"title": "BrownSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000060",
"duration": 304,
"bitRate": 20,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 5,
"averageRating": 5,
"track": 4,
"year": 2007,
"genre": "Electronic",
"size": 792375,
"discNumber": 1,
"suffix": "wma",
"contentType": "audio/x-ms-wma",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
},
{
"id": "300000055",
"parent": "200000002",
"title": "Red&GreenSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000055",
"duration": 400,
"bitRate": 64,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 5,
"year": 2007,
"genre": "Electronic",
"size": 3209886,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
randomSongs |
randomSongs |
Yes | The random songs list |
48 - getScanStatus
Returns the current status for media library scanning.
http://your-server/rest/getScanStatus Since 1.15.0
Returns the current status for media library scanning. Takes no extra parameters.
Parameters
Takes no extra parameters.
Example
http://your-server/rest/getScanStatus.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested scanStatus element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"scanStatus": {
"scanning": true,
"count": 1
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"scanStatus": {
"scanning": true,
"count": 0
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
scanStatus |
scanStatus |
Yes | The status of the scan |
49 - getShares
Returns information about shared media this user is allowed to manage.
http://your-server/rest/getShares Since 1.6.0
Returns information about shared media this user is allowed to manage. Takes no extra parameters.
Parameters
Takes no extra parameters.
Example
http://your-server/rest/getShares.view?&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested shares element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"shares": {
"share": [
{
"id": "12",
"url": "http://localhost:8989/share.php?id=12&secret=fXlKyEv3",
"description": "Forget and Remember (Comfort Fit)",
"username": "user",
"created": "2023-03-16T04:13:09+00:00",
"visitCount": 0,
"entry": [
{
"id": "300000116",
"parent": "200000021",
"title": "Can I Help U?",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000021",
"album": "Forget and Remember",
"artistId": "100000036",
"artist": "Comfort Fit",
"coverArt": "300000116",
"duration": 103,
"bitRate": 216,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 1,
"year": 2005,
"genre": "Hip-Hop",
"size": 2811819,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
},
{
"id": "300000121",
"parent": "200000021",
"title": "Planetary Picknick",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000021",
"album": "Forget and Remember",
"artistId": "100000036",
"artist": "Comfort Fit",
"coverArt": "300000121",
"duration": 358,
"bitRate": 238,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 2,
"year": 2005,
"genre": "Hip-Hop",
"size": 10715592,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
}
]
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"shares": {
"share": [
{
"id": "12",
"url": "http://localhost:8989/share.php?id=12&secret=fXlKyEv3",
"description": "Forget and Remember (Comfort Fit)",
"username": "user",
"created": "2023-03-16T04:13:09+00:00",
"visitCount": 0,
"entry": [
{
"id": "300000116",
"parent": "200000021",
"title": "Can I Help U?",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000021",
"album": "Forget and Remember",
"artistId": "100000036",
"artist": "Comfort Fit",
"coverArt": "300000116",
"duration": 103,
"bitRate": 216,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 1,
"year": 2005,
"genre": "Hip-Hop",
"size": 2811819,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
},
{
"id": "300000121",
"parent": "200000021",
"title": "Planetary Picknick",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000021",
"album": "Forget and Remember",
"artistId": "100000036",
"artist": "Comfort Fit",
"coverArt": "300000121",
"duration": 358,
"bitRate": 238,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 2,
"year": 2005,
"genre": "Hip-Hop",
"size": 10715592,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
}
]
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
shares |
shares |
Yes | The shares |
50 - getSimilarSongs
Returns a random collection of songs from the given artist and similar artists.
http://your-server/rest/getSimilarSongs 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.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The artist, album or song ID. | ||
count |
No | 50 | Max number of songs to return. |
Example
http://your-server/rest/getSimilarSongs.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested similarSongs element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"similarSongs": {
"song": [
{
"id": "300000060",
"parent": "200000002",
"title": "BrownSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000060",
"duration": 304,
"bitRate": 20,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 5,
"averageRating": 5,
"track": 4,
"year": 2007,
"genre": "Electronic",
"size": 792375,
"discNumber": 1,
"suffix": "wma",
"contentType": "audio/x-ms-wma",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
},
{
"id": "300000055",
"parent": "200000002",
"title": "Red&GreenSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000055",
"duration": 400,
"bitRate": 64,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 5,
"year": 2007,
"genre": "Electronic",
"size": 3209886,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"similarSongs": {
"song": [
{
"id": "300000060",
"parent": "200000002",
"title": "BrownSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000060",
"duration": 304,
"bitRate": 20,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 5,
"averageRating": 5,
"track": 4,
"year": 2007,
"genre": "Electronic",
"size": 792375,
"discNumber": 1,
"suffix": "wma",
"contentType": "audio/x-ms-wma",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
},
{
"id": "300000055",
"parent": "200000002",
"title": "Red&GreenSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000055",
"duration": 400,
"bitRate": 64,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 5,
"year": 2007,
"genre": "Electronic",
"size": 3209886,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
similarSongs |
similarSongs |
Yes | The similar songs list |
51 - getSimilarSongs2
Returns a random collection of songs from the given artist and similar artists.
http://your-server/rest/getSimilarSongs2 Since 1.11.0
Similar to getSimilarSongs, but organizes music according to ID3 tags.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The artist ID. | ||
count |
No | 50 | Max number of songs to return. |
Example
http://your-server/rest/getSimilarSongs2.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested similarSongs2 element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"similarSongs2": {
"song": [
{
"id": "300000060",
"parent": "200000002",
"title": "BrownSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000060",
"duration": 304,
"bitRate": 20,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 5,
"averageRating": 5,
"track": 4,
"year": 2007,
"genre": "Electronic",
"size": 792375,
"discNumber": 1,
"suffix": "wma",
"contentType": "audio/x-ms-wma",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
},
{
"id": "300000055",
"parent": "200000002",
"title": "Red&GreenSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000055",
"duration": 400,
"bitRate": 64,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 5,
"year": 2007,
"genre": "Electronic",
"size": 3209886,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"similarSongs2": {
"song": [
{
"id": "300000060",
"parent": "200000002",
"title": "BrownSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000060",
"duration": 304,
"bitRate": 20,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 5,
"averageRating": 5,
"track": 4,
"year": 2007,
"genre": "Electronic",
"size": 792375,
"discNumber": 1,
"suffix": "wma",
"contentType": "audio/x-ms-wma",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
},
{
"id": "300000055",
"parent": "200000002",
"title": "Red&GreenSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000055",
"duration": 400,
"bitRate": 64,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 5,
"year": 2007,
"genre": "Electronic",
"size": 3209886,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
similarSongs2 |
similarSongs2 |
Yes | The similar songs list |
52 - getSong
Returns details for a song.
http://your-server/rest/getSong Since 1.8.0
Returns details for a song.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The song ID. |
Example
http://your-server/rest/getSong.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested song element on success.
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
song |
song |
Yes | The song |
53 - getSongsByGenre
Returns songs in a given genre.
http://your-server/rest/getSongsByGenre Since 1.9.0
Returns songs in a given genre.
Parameters
| Parameter | Req. | OpenS. | 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. | |
musicFolderId |
No | (Since 1.12.0) Only return albums in the music folder with the given ID. See getMusicFolders. |
Example
http://your-server/rest/getSongsByGenre.view?genre=Rock&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested songsByGenre element on success.
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
songsByGenre |
songsByGenre |
Yes | The song |
54 - getStarred
Returns starred songs, albums and artists.
http://your-server/rest/getStarred Since 1.8.0
Returns starred songs, albums and artists.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
musicFolderId |
No | (Since 1.12.0) Only return results from the music folder with the given ID. See getMusicFolders. |
Example
http://your-server/rest/getStarred.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested starred element on success.
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
starred |
starred |
Yes | The song |
55 - getStarred2
Returns starred songs, albums and artists.
http://your-server/rest/getStarred2 Since 1.8.0
Similar to getStarred, but organizes music according to ID3 tags.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
musicFolderId |
No | (Since 1.12.0) Only return results from the music folder with the given ID. See getMusicFolders. |
Example
http://your-server/rest/getStarred2.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested starred2 element on success.
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
starred2 |
starred2 |
Yes | The song |
56 - getTopSongs
Returns top songs for the given artist.
http://your-server/rest/getTopSongs Since 1.13.0
Returns top songs for the given artist, using data from last.fm.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
artist |
Yes | The artist name. | ||
count |
No | 50 | Max number of songs to return. |
Example
http://your-server/rest/getTopSongs.view?artist=toto&u=demo&p=demo&v=1.13.0&c=AwesomeServerName&f=json
Result
A subsonic-response element with a nested topSongs element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"topSongs": {
"song": [
{
"id": "300000060",
"parent": "200000002",
"title": "BrownSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000060",
"duration": 304,
"bitRate": 20,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 5,
"averageRating": 5,
"track": 4,
"year": 2007,
"genre": "Electronic",
"size": 792375,
"discNumber": 1,
"suffix": "wma",
"contentType": "audio/x-ms-wma",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
},
{
"id": "300000055",
"parent": "200000002",
"title": "Red&GreenSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000055",
"duration": 400,
"bitRate": 64,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 5,
"year": 2007,
"genre": "Electronic",
"size": 3209886,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"topSongs": {
"song": [
{
"id": "300000060",
"parent": "200000002",
"title": "BrownSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000060",
"duration": 304,
"bitRate": 20,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"userRating": 5,
"averageRating": 5,
"track": 4,
"year": 2007,
"genre": "Electronic",
"size": 792375,
"discNumber": 1,
"suffix": "wma",
"contentType": "audio/x-ms-wma",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
},
{
"id": "300000055",
"parent": "200000002",
"title": "Red&GreenSmoke",
"isDir": false,
"isVideo": false,
"type": "music",
"albumId": "200000002",
"album": "Colorsmoke EP",
"artistId": "100000002",
"artist": "Synthetic",
"coverArt": "300000055",
"duration": 400,
"bitRate": 64,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"track": 5,
"year": 2007,
"genre": "Electronic",
"size": 3209886,
"discNumber": 1,
"suffix": "mp3",
"contentType": "audio/mpeg",
"path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
topSongs |
topSongs |
Yes | The top songs list |
57 - getUser
Get details about a given user, including which authorization roles and folder access it has.
http://your-server/rest/getUser Since 1.3.0
Get details about a given user, including which authorization roles and folder access it has. Can be used to enable/disable certain features in the client, such as jukebox control.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
username |
Yes | The name of the user to retrieve. You can only retrieve your own user unless you have admin privileges. |
Example
http://your-server/rest/getUser.view?username=tata&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested user element on success.
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
user |
user |
Yes | The user |
58 - getUsers
Get details about all users, including which authorization roles and folder access they have
http://your-server/rest/getUsers Since 1.8.0
Get details about all users, including which authorization roles and folder access they have. Only users with admin privileges are allowed to call this method.
Parameters
Takes no extra parameters.
Example
http://your-server/rest/getUsers.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested users element on success.
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
users |
users |
Yes | The users |
59 - getVideoInfo
Returns details for a video.
http://your-server/rest/getVideoInfo Since 1.14.0
Returns details for a video, including information about available audio tracks, subtitles (captions) and conversions.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The video ID. |
Example
http://your-server/rest/getVideoInfo.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested videoInfo element on success.
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
videoInfo |
videoInfo |
Yes | The song |
60 - getVideos
Returns all video files.
http://your-server/rest/getVideos Since 1.8.0
Returns all video files.
Parameters
Takes no extra parameters.
Example
http://your-server/rest/getVideos.view?&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested videos element on success.
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
videos |
videos |
Yes | The videos |
61 - hls
Downloads a given media file.
http://your-server/rest/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.
Parameters
| Parameter | Req. | OpenS. | 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. SeegetVideoInfo for how to get the list of available audio tracks for a video. |
Example
http://your-server/rest/hls.m3u8?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
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”).
62 - jukeboxControl
Controls the jukebox, i.e., playback directly on the server’s audio hardware.
http://your-server/rest/jukeboxControl 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).
Parameters
| Parameter | Req. | OpenS. | 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. |
Example
http://your-server/rest/jukeboxControl.view?action=get&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested :
jukeboxStatusfor all actions butgetjukeboxPlaylistforgetaction
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
jukeboxStatus |
jukeboxstatus |
Yes | The jukeboxstatus | |
jukeboxPlaylist |
jukeboxPlaylist |
Yes | The jukeboxstatus |
63 - ping
Used to test connectivity with the server.
http://your-server/rest/ping Since 1.0.0
Test connectivity with the server.
Parameters
Takes no extra parameters.
Example
http://your-server/rest/ping.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}64 - refreshPodcasts
Requests the server to check for new Podcast episodes.
http://your-server/rest/refreshPodcasts 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).
Parameters
Takes no extra parameters.
Example
http://your-server/rest/refreshPodcasts.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}65 - savePlayQueue
Saves the state of the play queue for this user.
http://your-server/rest/savePlayQueue Since 1.12.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).
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
No | 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. |
Example
http://your-server/rest/savePlayQueue.view?id=123¤t=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}OpenSubsonic
Noteid is optional. Send a call without any parameters to clear the currently saved queue.
66 - scrobble
Registers the local playback of one or more media files.
http://your-server/rest/scrobble Since 1.5.0
Registers the local playback of one or more media files. Typically used when playing media that is cached on the client. This operation includes the following:
- “Scrobbles” the media files on last.fm if the user has configured his/her last.fm credentials on the server.
- Updates the play count and last played timestamp for the media files. (Since 1.11.0)
- Makes the media files appear in the “Now playing” page in the web app, and appear in the list of songs returned by
getNowPlaying(Since 1.11.0)
Since 1.8.0 you may specify multiple id (and optionally time) parameters to scrobble multiple files.
Parameters
| Parameter | Req. | OpenS. | 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. |
Example
http://your-server/rest/scrobble.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}67 - search
Returns a listing of files matching the given search criteria. Supports paging through the result.
http://your-server/rest/search 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.
Parameters
| Parameter | Req. | OpenS. | 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. |
Example
http://your-server/rest/search.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested searchResult element on success.
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
searchResult |
searchResult |
Yes | The result |
68 - search2
Returns a listing of files matching the given search criteria. Supports paging through the result.
http://your-server/rest/search2 Since 1.4.0
Returns albums, artists and songs matching the given search criteria. Supports paging through the result.
Parameters
| Parameter | Req. | OpenS. | 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. | |
musicFolderId |
No | (Since 1.12.0) Only return results from the music folder with the given ID. See getMusicFolders. |
Example
http://your-server/rest/search2.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested searchResult2 element on success.
// TODO// TODO| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
searchResult2 |
searchResult2 |
Yes | The result |
69 - search3
Returns albums, artists and songs matching the given search criteria. Supports paging through the result.
http://your-server/rest/search3 Since 1.8.0
Returns albums, artists and songs matching the given search criteria. Supports paging through the result.
Music is organized according to ID3 tags.
Parameters
| Parameter | Requ. | OpenS. | Default | Comment |
|---|---|---|---|---|
query |
Yes | See below* | 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. | |
musicFolderId |
No | (Since 1.12.0) Only return results from music folder with the given ID. See getMusicFolders. |
OpenSubsonic
Servers must support an empty query and return all the data to allow clients to properly access all the media information for offline sync.Example
http://your-server/rest/search3.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json&query=""&artistCount=1&albumCount=1&songCount=1
Result
A subsonic-response with a nested searchResult3 element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"searchResult3": {
"artist": [
{
"id": "37ec820ca7193e17040c98f7da7c4b51",
"name": "2 Mello",
"coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
"albumCount": 1,
"userRating": 5,
"artistImageUrl": "https://demo.org/image.jpg"
}
],
"album": [
{
"id": "ad0f112b6dcf83de5e9cae85d07f0d35",
"name": "8-bit lagerfeuer",
"artist": "pornophonique",
"year": 2007,
"coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
"starred": "2023-03-22T01:51:06Z",
"duration": 1954,
"playCount": 97,
"played": "2023-03-28T00:45:13Z",
"created": "2023-03-10T02:19:35.784818075Z",
"artistId": "91c3901ac465b9efc439e4be4270c2b6",
"userRating": 4,
"songCount": 8
}
],
"song": [
{
"id": "082f435a363c32c57d5edb6a678a28d4",
"parent": "e8a0685e3f3ec6f251649af2b58b8617",
"isDir": false,
"title": "\"polar expedition\"",
"album": "Live at The Casbah - 2005-04-29",
"artist": "The New Deal",
"track": 4,
"year": 2005,
"coverArt": "mf-082f435a363c32c57d5edb6a678a28d4_6410b3ce",
"size": 19866778,
"contentType": "audio/flac",
"suffix": "flac",
"starred": "2023-03-27T09:45:27Z",
"duration": 178,
"bitRate": 880,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"path": "The New Deal/Live at The Casbah - 2005-04-29/04 - \"polar expedition\".flac",
"playCount": 8,
"played": "2023-03-26T22:27:46Z",
"discNumber": 1,
"created": "2023-03-14T17:51:22.112827504Z",
"albumId": "e8a0685e3f3ec6f251649af2b58b8617",
"artistId": "97e0398acf63f9fb930d7d4ce209a52b",
"type": "music",
"isVideo": false
}
]
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"searchResult3": {
"artist": [
{
"id": "37ec820ca7193e17040c98f7da7c4b51",
"name": "2 Mello",
"coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
"albumCount": 1,
"userRating": 5,
"artistImageUrl": "https://demo.org/image.jpg"
}
],
"album": [
{
"id": "ad0f112b6dcf83de5e9cae85d07f0d35",
"name": "8-bit lagerfeuer",
"artist": "pornophonique",
"year": 2007,
"coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
"starred": "2023-03-22T01:51:06Z",
"duration": 1954,
"playCount": 97,
"played": "2023-03-28T00:45:13Z",
"created": "2023-03-10T02:19:35.784818075Z",
"artistId": "91c3901ac465b9efc439e4be4270c2b6",
"userRating": 4,
"songCount": 8
}
],
"song": [
{
"id": "082f435a363c32c57d5edb6a678a28d4",
"parent": "e8a0685e3f3ec6f251649af2b58b8617",
"isDir": false,
"title": "\"polar expedition\"",
"album": "Live at The Casbah - 2005-04-29",
"artist": "The New Deal",
"track": 4,
"year": 2005,
"coverArt": "mf-082f435a363c32c57d5edb6a678a28d4_6410b3ce",
"size": 19866778,
"contentType": "audio/flac",
"suffix": "flac",
"starred": "2023-03-27T09:45:27Z",
"duration": 178,
"bitRate": 880,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"path": "The New Deal/Live at The Casbah - 2005-04-29/04 - \"polar expedition\".flac",
"playCount": 8,
"played": "2023-03-26T22:27:46Z",
"discNumber": 1,
"created": "2023-03-14T17:51:22.112827504Z",
"albumId": "e8a0685e3f3ec6f251649af2b58b8617",
"artistId": "97e0398acf63f9fb930d7d4ce209a52b",
"type": "music",
"isVideo": false
}
]
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
searchResult3 |
searchResult3 |
Yes | The result of the search |
70 - setRating
Sets the rating for a music file.
http://your-server/rest/setRating Since 1.6.0
Sets the rating for a music file.
Parameters
| Parameter | Req. | OpenS. | 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. |
Example
http://your-server/rest/setRating.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}71 - star
Attaches a star to a song, album or artist.
http://your-server/rest/star Since 1.8.0
Attaches a star to a song, album or artist.
Parameters
| Parameter | Req. | OpenS. | 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. |
Example
http://your-server/rest/star.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}72 - startScan
Initiates a rescan of the media libraries.
http://your-server/rest/startScan Since 1.15.0
Initiates a rescan of the media libraries. Takes no extra parameters.
Parameters
Takes no extra parameters.
Example
http://your-server/rest/startScan.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested scanStatus element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"scanStatus": {
"scanning": true,
"count": 1
}
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"scanStatus": {
"scanning": true,
"count": 0
}
}
}| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
scanStatus |
scanStatus |
Yes | The status of the scan |
73 - stream
Streams a given media file.
http://your-server/rest/stream Since 1.0.0
Streams a given media file.
Parameters
| Parameter | Req. | OpenS. | 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 | No / Yes | By default only applicable to video streaming. If specified, start streaming at the given offset (in seconds) into the media. The Transcode Offet extension enables the parameter to music too. |
|
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. | |
converted |
No | false | (Since 1.14.0) Only applicable to video streaming. Servers can optimize videos for streaming by converting them to MP4. If a conversion exists for the video in question, then setting this parameter to “true” will cause the converted video to be returned instead of the original. |
Example
http://your-server/rest/stream.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
Returns binary data on success, or an XML document on error (in which case the HTTP content type will start with “text/xml”).
OpenSubsonic
OpenSubsonic servers must not count access to this endpoint as a play and increase playcount. Clients can use the Scrobble endpoint to indicate that a media is played ensuring proper data in all cases.
If the server support the Transcode Offet extension, then it must accept the timeOffset parameter for music too.
74 - tokenInfo
Returns information about an API key
OpenSubsonic version: 1
OpenSubsonic extension name apiKeyAuthentication (As returned by getOpenSubsonicExtensions)
Returns data about an API key.
http://your-server/rest/tokenInfo
Parameters
None
Example
http://your-server/rest/tokenInfo.view?apiKey=1234&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested tokenInfo on success, or error 44 on invalid token.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true,
"tokenInfo": {
"username": "token username"
}
}
}<subsonic-response status="ok" version="1.16.1" type="AwesomeServerName" serverVersion="0.1.3 (tag)" openSubsonic="true">
<tokenInfo username="token username"></tokenInfo>
</subsonic-response>Does not exist.| Field | Type | Req. | OpenS. | Details |
|---|---|---|---|---|
tokenInfo |
tokenInfo |
Yes | Yes | Information about the token |
75 - unstar
Attaches a star to a song, album or artist.
http://your-server/rest/unstar Since 1.8.0
Removes a star to a song, album or artist.
Parameters
| Parameter | Req. | OpenS. | 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. |
Example
http://your-server/rest/unstar.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}76 - updateInternetRadioStation
Updates an existing internet radio station.
http://your-server/rest/updateInternetRadioStation Since 1.16.0
Updates an existing internet radio station. Only users with admin privileges are allowed to call this method.
Parameters
| Parameter | Req. | OpenS. | Default | Comment |
|---|---|---|---|---|
id |
Yes | The ID of the station. | ||
streamUrl |
Yes | The stream URL for the station. | ||
name |
Yes | The user-defined name for the station. | ||
homepageUrl |
No | The home page URL for the station. |
Example
http://your-server/rest/updateInternetRadioStation.view?id=123&streamUrl=url&name=test&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}77 - updatePlaylist
Updates a playlist. Only the owner of a playlist is allowed to update it.
http://your-server/rest/updatePlaylist Since 1.8.0
Updates a playlist. Only the owner of a playlist is allowed to update it.
Parameters
| Parameter | Req. | OpenS. | 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. |
||
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. |
Example
http://your-server/rest/updatePlaylist.view?playlistId=123&name=test&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}78 - updateShare
Updates the description and/or expiration date for an existing share.
http://your-server/rest/updateShare Since 1.6.0
Updates the description and/or expiration date for an existing share.
Parameters
| Parameter | Req. | OpenS. | 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. |
Example
http://your-server/rest/updateShare.view?id=123&description=test&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}79 - updateUser
Modifies an existing user on the server.
http://your-server/rest/updateUser Since 1.10.1
Modifies an existing user on the server.
Parameters
| Parameter | Req. | OpenS. | 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 personal 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. | ||
videoConversionRole |
No | false | (Since 1.15.0) Whether the user is allowed to start video conversions. | |
musicFolderId |
No | (Since 1.12.0) IDs of the music folders the user is allowed access to. Include the parameter once for each folder. | ||
maxBitRate |
No | (Since 1.13.0) The maximum bit rate (in Kbps) for the user. Audio streams of higher bit rates are automatically downsampled to this bit rate. Legal values: 0 (no limit), 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320. |
Example
http://your-server/rest/updateUser.view?username=test&password=test&email=test@test.com&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
An empty subsonic-response element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
}
}{
"subsonic-response": {
"status": "ok",
"version": "1.16.1"
}
}