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

ParameterReq.OpenS.DefaultComment
messageYesThe chat message.

Example

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

ParameterReq.OpenS.DefaultComment
usernameYesThe name of the user which should change its password.
passwordYesThe new password of the new user, either in clear text of hex-encoded (see above).

Example

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

ParameterReq.OpenS.DefaultComment
idYesID of the media file to bookmark. If a bookmark already exists for this file it will be overwritten.
positionYesThe position (in milliseconds) within the media file.
commentNoA user-defined comment.

Example

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

ParameterReq.OpenS.DefaultComment
streamUrlYesThe stream URL for the station.
nameYesThe user-defined name for the station.
homepageUrlNoThe home page URL for the station.

Example

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

ParameterReq.OpenS.DefaultComment
playlistIdYes (if updating)The playlist ID.
nameYes (if creating)The human-readable name of the playlist.
songIdNoID of a song in the playlist. Use one songId parameter for each song in the playlist.

Example

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
playlistplaylistYesThe 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

ParameterReq.OpenS.DefaultComment
urlYesThe URL of the Podcast to add.

Example

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

ParameterReq.OpenS.DefaultComment
idYesID of a song, album or video to share. Use one id parameter for each entry to share.
descriptionNoA user-defined description that will be displayed to people visiting the shared media.
expiresNoThe time at which the share expires. Given as milliseconds since 1970.

Example

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"
            }
          ]
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
sharessharesYesThe 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

ParameterReq.OpenS.DefaultComment
usernameYesThe name of the new user.
passwordYesThe password of the new user, either in clear text of hex-encoded (see above).
emailYesThe email address of the new user.
ldapAuthenticatedNofalseWhether the user is authenicated in LDAP.
adminRoleNofalseWhether the user is administrator.
settingsRoleNotrueWhether the user is allowed to change personal settings and password.
streamRoleNotrueWhether the user is allowed to play files.
jukeboxRoleNofalseWhether the user is allowed to play files in jukebox mode.
downloadRoleNofalseWhether the user is allowed to download files.
uploadRoleNofalseWhether the user is allowed to upload files.
playlistRoleNofalseWhether the user is allowed to create and delete playlists. Since 1.8.0, changing this role has no effect.
coverArtRoleNofalseWhether the user is allowed to change cover art and tags.
commentRoleNofalseWhether the user is allowed to create and edit comments and ratings.
podcastRoleNofalseWhether the user is allowed to administrate Podcasts.
shareRoleNofalse(Since 1.8.0) Whether the user is allowed to share files with anyone.
videoConversionRoleNofalse(Since 1.15.0) Whether the user is allowed to start video conversions.
musicFolderIdNoAll folders(Since 1.12.0) IDs of the music folders the user is allowed access to. Include the parameter once for each folder.

Example

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

ParameterReq.OpenS.DefaultComment
idYesID of the media file for which to delete the bookmark. Other users’ bookmarks are not affected.

Example

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

ParameterReq.OpenS.DefaultComment
idYesThe ID for the station.

Example

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

ParameterReq.OpenS.DefaultComment
idYesID of the playlist to delete, as obtained by getPlaylists.

Example

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

ParameterReq.OpenS.DefaultComment
idYesThe ID of the Podcast channel to delete.

Example

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

ParameterReq.OpenS.DefaultComment
idYesThe ID of the Podcast episode to delete.

Example

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

ParameterReq.OpenS.DefaultComment
idYesID of the share to delete.

Example

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

ParameterReq.OpenS.DefaultComment
usernameYesThe name of the user to delete.

Example

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

ParameterReq.OpenS.DefaultComment
idYesA string which uniquely identifies the file to stream. Obtained by calls to getMusicDirectory.

Example

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

ParameterReq.OpenS.DefaultComment
idYesThe ID of the Podcast episode to download.

Example

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

ParameterReq.OpenS.DefaultComment
idYesThe album ID.

Example

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
albumalbumYesThe 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

ParameterReq.OpenS.DefaultComment
idYesThe album ID or song ID.

Example

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"
    }
  }
}
FieldTypeReq.OpenS.Details
albumInfoalbumInfoYesThe 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

ParameterReq.OpenS.DefaultComment
idYesThe album ID or song ID.

Example

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"
    }
  }
}
FieldTypeReq.OpenS.Details
albumInfoalbumInfoYesThe 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

ParameterReq.OpenS.DefaultComment
typeYesThe 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.
sizeNo10The number of albums to return. Max 500.
offsetNo0The list offset. Useful if you for example want to page through the list of newest albums.
fromYearYes (if type is byYear)The first year in the range. If fromYear > toYear a reverse chronological list is returned.
toYearYes (if type is byYear)The last year in the range.
genreYes (if type is byGenre)The name of the genre, e.g., “Rock”.
musicFolderIdNo(Since 1.11.0) Only return albums in the music folder with the given ID. See getMusicFolders.

Example

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
albumListalbumListYesThe 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

ParameterReq.OpenS.DefaultComment
typeYesThe 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.
sizeNo10The number of albums to return. Max 500.
offsetNo0The list offset. Useful if you for example want to page through the list of newest albums.
fromYearYes (if type is byYear)The first year in the range. If fromYear > toYear a reverse chronological list is returned.
toYearYes (if type is byYear)The last year in the range.
genreYes (if type is byGenre)The name of the genre, e.g., “Rock”.
musicFolderIdNo(Since 1.11.0) Only return albums in the music folder with the given ID. See getMusicFolders.

Example

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
albumList2albumList2YesThe 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

ParameterReq.OpenS.DefaultComment
idYesThe artist ID.

Example

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": "37ec820ca7193e17040c98f7da7c4b51",
      "name": "2 Mello",
      "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
      "albumCount": 1,
      "userRating": 5,
      "artistImageUrl": "https://demo.org/image.jpg",
      "starred": "2017-04-11T10:42:50.842Z",
      "musicBrainzId": "189002e7-3285-4e2e-92a3-7f6c30d407a2",
      "sortName": "Mello (2)",
      "roles": [
        "artist",
        "albumartist",
        "composer"
      ],
      "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": "37ec820ca7193e17040c98f7da7c4b51",
      "name": "2 Mello",
      "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
      "albumCount": 1,
      "userRating": 5,
      "artistImageUrl": "https://demo.org/image.jpg",
      "starred": "2017-04-11T10:42:50.842Z",
      "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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
artistartistYesThe 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

ParameterReq.OpenS.DefaultComment
idYesThe artist, album or song ID.
countNo20Max number of similar artists to return.
includeNotPresentNofalseWhether to return artists that are not present in the media library.

Example

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": "Empty 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": "Empty 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"
    }
  }
}
FieldTypeReq.OpenS.Details
artistInfoartistInfoYesThe 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

ParameterReq.OpenS.DefaultComment
idYesThe artist, album or song ID.
countNo20Max number of similar artists to return.
includeNotPresentNofalseWhether to return artists that are not present in the media library.

Example

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": "Empty 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": "Empty 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"
    }
  }
}
FieldTypeReq.OpenS.Details
artistInfo2artistInfo2YesThe 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

ParameterReq.OpenS.DefaultComment
musicFolderIdNoIf specified, only return artists in the music folder with the given ID. See getMusicFolders.

Example

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
            }
          ]
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
artistsartistsYesThe 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

ParameterReq.OpenS.DefaultComment
usernameYesThe user in question..

Example

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

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
bookmarksbookmarksYesThe 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

ParameterReq.OpenS.DefaultComment
idYesThe ID of the video.
formatNoPreferred captions format (“srt” or “vtt”).

Example

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

ParameterReq.OpenS.DefaultComment
sinceNoOnly return messages newer than this time (in millis since Jan 1 1970).

Example

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
chatMessageschatMessagesYesThe message list

31 - getCoverArt

Returns a cover art image.

http://your-server/rest/getCoverArt Since 1.0.0

Returns a cover art image.

Parameters

ParameterReq.OpenS.DefaultComment
idYesThe coverArt ID. Returned by most entities likes Child or AlbumID3
sizeNoIf specified, scale image to this size.

Example

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

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
genresgenresYesThe 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

ParameterReq.OpenS.DefaultComment
musicFolderIdNoIf specified, only return artists in the music folder with the given ID. See getMusicFolders.
ifModifiedSinceNoIf specified, only return a result if the artist collection has changed since the given time (in milliseconds since 1 Jan 1970).

Example

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>
FieldTypeReq.OpenS.Details
indexesindexesYesThe 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

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
internetRadioStationsinternetRadioStationsYesThe 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

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"
    }
  }
}
FieldTypeReq.OpenS.Details
licenselicenseYesThe 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

ParameterReq.OpenS.DefaultComment
artistNoThe artist name.
titleNoThe song title.

Example

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?"
    }
  }
}
FieldTypeReq.OpenS.Details
lyricslyricsYesThe 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

ParameterReq.OpenS.DefaultComment
idYesYesThe track ID.

Example

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.
FieldTypeReq.OpenS.Details
lyricsListlyricsListYesYesList 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

ParameterReq.OpenS.DefaultComment
idYesA string which uniquely identifies the music folder. Obtained by calls to getIndexes or getMusicDirectory.

Example

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
directorydirectoryYesThe 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

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
musicFoldersmusicFoldersYesThe 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

ParameterReq.OpenS.DefaultComment
countNo20The maximum number of episodes to return.

Example

Result

A subsonic-response element with a nested newestPodcasts element on success.

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "newestPodcasts": {
      "episode": [
        {
          "id": "7390",
          "parent": "7389",
          "isDir": "false",
          "title": "Jonas Gahr Støre",
          "album": "NRK – Hallo P3",
          "artist": "Podcast",
          "year": "2015",
          "coverArt": "7389",
          "size": "41808585",
          "contentType": "audio/mpeg",
          "suffix": "mp3",
          "duration": "2619",
          "bitRate": "128",
          "isVideo": "false",
          "created": "2015-09-07T20:07:31.000Z",
          "artistId": "453",
          "type": "podcast",
          "streamId": "7410",
          "channelId": "17",
          "description": "Jonas Gahr Støre fra Arbeiderpartiet er med i dagens partilederutspørring i Hallo P3!",
          "status": "completed",
          "publishDate": "2015-09-07T15:29:00.000Z"
        }
      ]
    }
  }
}
{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "newestPodcasts": {
      "episode": [
        {
          "id": "7390",
          "parent": "7389",
          "isDir": "false",
          "title": "Jonas Gahr Støre",
          "album": "NRK – Hallo P3",
          "artist": "Podcast",
          "year": "2015",
          "coverArt": "7389",
          "size": "41808585",
          "contentType": "audio/mpeg",
          "suffix": "mp3",
          "duration": "2619",
          "bitRate": "128",
          "isVideo": "false",
          "created": "2015-09-07T20:07:31.000Z",
          "artistId": "453",
          "type": "podcast",
          "streamId": "7410",
          "channelId": "17",
          "description": "Jonas Gahr Støre fra Arbeiderpartiet er med i dagens partilederutspørring i Hallo P3!",
          "status": "completed",
          "publishDate": "2015-09-07T15:29:00.000Z"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
newestPodcastsNewestPodcastsYesThe 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

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
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
nowPlayingnowPlayingYesThe 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

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.
FieldTypeReq.OpenS.Details
openSubsonicExtensionsAn array of openSubsonicExtensionYesThe list of supported extensions

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

ParameterReq.OpenS.DefaultComment
idyesID of the playlist to return, as obtained by getPlaylists.

Example

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
playlistplaylistYesThe 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

ParameterReq.OpenS.DefaultComment
usernameno(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

Result

A subsonic-response element with a nested playlists element on success.

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "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
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
playlistsplaylistsYesThe 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

Result

A subsonic-response element with a nested playQueue element on success.

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "playQueue": {
      "current": "1234",
      "position": 1000,
      "username": "user",
      "changed": "2023-03-10T02:19:35.784818075Z",
      "changedBy": "example client",
      "entry": [
        {
          "id": "1234",
          "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": "1234",
          "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"
        }
      ]
    }
  }
}
{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "playQueue": {
      "current": "1234",
      "position": 1000,
      "username": "user",
      "changed": "2023-03-10T02:19:35.784818075Z",
      "changedBy": "example client",
      "entry": [
        {
          "id": "1234",
          "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": "1234",
          "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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
playQueueplayQueueYesThe play queue

46 - getPodcastEpisode

Returns details for a podcast episode.

OpenSubsonic version: 1

OpenSubsonic extension name getPodcastEpisode (As returned by getOpenSubsonicExtensions) http://your-server/rest/getPodcastEpisode

Returns details for a podcast episode.

Parameters

ParameterReq.OpenS.DefaultComment
idYesYesThe podcast episode ID.

Example

Result

A subsonic-response element with a nested podcastEpisode element on success.

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "podcastEpisode": {
      "id": "7390",
      "parent": "7389",
      "isDir": "false",
      "title": "Jonas Gahr Støre",
      "album": "NRK – Hallo P3",
      "artist": "Podcast",
      "year": "2015",
      "coverArt": "7389",
      "size": "41808585",
      "contentType": "audio/mpeg",
      "suffix": "mp3",
      "duration": "2619",
      "bitRate": "128",
      "isVideo": "false",
      "created": "2015-09-07T20:07:31.000Z",
      "artistId": "453",
      "type": "podcast",
      "streamId": "7410",
      "channelId": "17",
      "description": "Jonas Gahr Støre fra Arbeiderpartiet er med i dagens partilederutspørring i Hallo P3!",
      "status": "completed",
      "publishDate": "2015-09-07T15:29:00.000Z"
    }
  }
}
Does not exist
FieldTypeReq.OpenS.Details
podcastEspisodepodcastEpisodeYesThe podcast episode

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

ParameterReq.OpenS.DefaultComment
includeEpisodesNotrue(Since 1.9.0) Whether to include Podcast episodes in the returned result.
idNo(Since 1.9.0) If specified, only return the Podcast channel with this ID.

Example

Result

A subsonic-response element with a nested podcasts element on success.

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "podcasts": {
      "channel": [
        {
          "id": "7390",
          "parent": "7389",
          "isDir": "false",
          "title": "Jonas Gahr Støre",
          "album": "NRK – Hallo P3",
          "artist": "Podcast",
          "year": "2015",
          "coverArt": "7389",
          "size": "41808585",
          "contentType": "audio/mpeg",
          "suffix": "mp3",
          "duration": "2619",
          "bitRate": "128",
          "isVideo": "false",
          "created": "2015-09-07T20:07:31.000Z",
          "artistId": "453",
          "type": "podcast",
          "streamId": "7410",
          "channelId": "17",
          "description": "Jonas Gahr Støre fra Arbeiderpartiet er med i dagens partilederutspørring i Hallo P3!",
          "status": "completed",
          "publishDate": "2015-09-07T15:29:00.000Z"
        },
        {
          "id": "3",
          "url": "https://example.com/404",
          "status": "error",
          "errorMessage": "Not Found"
        }
      ]
    }
  }
}
{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
      "channel": [
        {
          "id": "7390",
          "parent": "7389",
          "isDir": "false",
          "title": "Jonas Gahr Støre",
          "album": "NRK – Hallo P3",
          "artist": "Podcast",
          "year": "2015",
          "coverArt": "7389",
          "size": "41808585",
          "contentType": "audio/mpeg",
          "suffix": "mp3",
          "duration": "2619",
          "bitRate": "128",
          "isVideo": "false",
          "created": "2015-09-07T20:07:31.000Z",
          "artistId": "453",
          "type": "podcast",
          "streamId": "7410",
          "channelId": "17",
          "description": "Jonas Gahr Støre fra Arbeiderpartiet er med i dagens partilederutspørring i Hallo P3!",
          "status": "completed",
          "publishDate": "2015-09-07T15:29:00.000Z"
        },
        {
          "id": "3",
          "url": "https://example.com/404",
          "status": "error",
          "errorMessage": "Not Found"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
podcastspodcastsYesThe podacsts

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

ParameterReq.OpenS.DefaultComment
sizeNo10The maximum number of songs to return. Max 500.
genreNoOnly returns songs belonging to this genre.
fromYearNoOnly return songs published after or in this year.
toYearNoOnly return songs published before or in this year.
musicFolderIdNoOnly return songs in the music folder with the given ID. See getMusicFolders.

Example

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
randomSongssongsYesThe random songs list

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

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
    }
  }
}
FieldTypeReq.OpenS.Details
scanStatusscanStatusYesThe status of the scan

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

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"
            }
          ]
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
sharessharesYesThe shares

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

ParameterReq.OpenS.DefaultComment
idYesThe artist, album or song ID.
countNo50Max number of songs to return.

Example

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
similarSongssimilarSongsYesThe similar songs list

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

ParameterReq.OpenS.DefaultComment
idYesThe artist ID.
countNo50Max number of songs to return.

Example

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
similarSongs2similarSongs2YesThe similar songs list

53 - getSong

Returns details for a song.

http://your-server/rest/getSong Since 1.8.0

Returns details for a song.

Parameters

ParameterReq.OpenS.DefaultComment
idYesThe song ID.

Example

Result

A subsonic-response element with a nested song element on success.

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "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",
      "mediaType": "song",
      "isVideo": false,
      "bpm": 134,
      "comment": "This is a song comment",
      "sortName": "Polar expedition",
      "musicBrainzId": "189002e7-3285-4e2e-92a3-7f6c30d407a2",
      "genres": [
        {
          "name": "Hip-Hop"
        },
        {
          "name": "East coast"
        }
      ],
      "artists": [
        {
          "id": "ar-1",
          "name": "Artist 1"
        },
        {
          "id": "ar-2",
          "name": "Artist 2"
        }
      ],
      "displayArtist": "Artist 1 feat. Artist 2",
      "albumArtists": [
        {
          "id": "ar-6",
          "name": "Artist 6"
        },
        {
          "id": "ar-7",
          "name": "Artist 7"
        }
      ],
      "displayAlbumArtist": "Artist 6 & Artist 7",
      "contributors": [
        {
          "role": "composer",
          "artist": {
            "id": "ar-3",
            "name": "Artist 3"
          }
        },
        {
          "role": "composer",
          "artist": {
            "id": "ar-4",
            "name": "Artist 4"
          }
        },
        {
          "role": "lyricist",
          "artist": {
            "id": "ar-5",
            "name": "Artist 5"
          }
        },
        {
          "role": "performer",
          "subRole": "Bass",
          "artist": {
            "id": "ar-5",
            "name": "Artist 5"
          }
        }
      ],
      "displayComposer": "Artist 3, Artist 4",
      "moods": [
        "slow",
        "cool"
      ],
      "replayGain": {
        "trackGain": 0.1,
        "albumGain": 1.1,
        "trackPeak": 9.2,
        "albumPeak": 9,
        "baseGain": 0
      }
    }
  }
}
{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "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,
      "discNumber": 1,
      "created": "2023-03-14T17:51:22.112827504Z",
      "albumId": "e8a0685e3f3ec6f251649af2b58b8617",
      "artistId": "97e0398acf63f9fb930d7d4ce209a52b",
      "type": "music",
      "isVideo": false
    }
  }
}
FieldTypeReq.OpenS.Details
songChildYesThe song

54 - getSongsByGenre

Returns songs in a given genre.

http://your-server/rest/getSongsByGenre Since 1.9.0

Returns songs in a given genre.

Parameters

ParameterReq.OpenS.DefaultComment
genreYesThe genre, as returned by getGenres.
countNo10The maximum number of songs to return. Max 500.
offsetNo0The offset. Useful if you want to page through the songs in a genre.
musicFolderIdNo(Since 1.12.0) Only return albums in the music folder with the given ID. See getMusicFolders.

Example

Result

A subsonic-response element with a nested songsByGenre element on success.

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "songsByGenre": {
      "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"
        }
      ]
    }
  }
}
{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "songsByGenre": {
      "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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
songsByGenresongsYesThe songs list

55 - getStarred

Returns starred songs, albums and artists.

http://your-server/rest/getStarred Since 1.8.0

Returns starred songs, albums and artists.

Parameters

ParameterReq.OpenS.DefaultComment
musicFolderIdNo(Since 1.12.0) Only return results from the music folder with the given ID. See getMusicFolders.

Example

Result

A subsonic-response element with a nested starred element on success.

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "starred": {
      "artist": [
        {
          "id": "100000002",
          "name": "Synthetic",
          "coverArt": "ar-100000002",
          "starred": "2021-02-22T05:54:18Z"
        }
      ],
      "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": "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,
          "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",
    "starred": {
      "artist": [
        {
          "id": "100000002",
          "name": "Synthetic",
          "coverArt": "ar-100000002",
          "starred": "2021-02-22T05:54:18Z"
        }
      ],
      "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": "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,
          "discNumber": 1,
          "created": "2023-03-14T17:51:22.112827504Z",
          "albumId": "e8a0685e3f3ec6f251649af2b58b8617",
          "artistId": "97e0398acf63f9fb930d7d4ce209a52b",
          "type": "music",
          "isVideo": false
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
starredstarredYesThe song

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

ParameterReq.OpenS.DefaultComment
musicFolderIdNo(Since 1.12.0) Only return results from the music folder with the given ID. See getMusicFolders.

Example

Result

A subsonic-response element with a nested starred2 element on success.

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "starred2": {
      "artist": [
        {
          "id": "37ec820ca7193e17040c98f7da7c4b51",
          "name": "2 Mello",
          "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
          "albumCount": 1,
          "userRating": 5,
          "artistImageUrl": "https://demo.org/image.jpg",
          "starred": "2017-04-11T10:42:50.842Z"
        }
      ],
      "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,
          "genre": "Hip-Hop",
          "created": "2023-03-10T02:19:35.784818075Z",
          "artistId": "91c3901ac465b9efc439e4be4270c2b6",
          "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,
          "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",
    "starred2": {
      "artist": [
        {
          "id": "37ec820ca7193e17040c98f7da7c4b51",
          "name": "2 Mello",
          "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
          "albumCount": 1,
          "userRating": 5,
          "artistImageUrl": "https://demo.org/image.jpg",
          "starred": "2017-04-11T10:42:50.842Z"
        }
      ],
      "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,
          "genre": "Hip-Hop",
          "created": "2023-03-10T02:19:35.784818075Z",
          "artistId": "91c3901ac465b9efc439e4be4270c2b6",
          "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,
          "discNumber": 1,
          "created": "2023-03-14T17:51:22.112827504Z",
          "albumId": "e8a0685e3f3ec6f251649af2b58b8617",
          "artistId": "97e0398acf63f9fb930d7d4ce209a52b",
          "type": "music",
          "isVideo": false
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
starred2starred2YesThe song

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

ParameterReq.OpenS.DefaultComment
artistYesThe artist name.
countNo50Max number of songs to return.

Example

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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
topSongstopSongsYesThe top songs list

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

ParameterReq.OpenS.DefaultComment
usernameYesThe name of the user to retrieve. You can only retrieve your own user unless you have admin privileges.

Example

Result

A subsonic-response element with a nested user element on success.

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "user": {
      "folder": [
          1,
          3
      ],
      "username": "sindre",
      "email": "sindre@activeobjects.no",
      "scrobblingEnabled": "true",
      "adminRole": "false",
      "settingsRole": "true",
      "downloadRole": "true",
      "uploadRole": "false",
      "playlistRole": "true",
      "coverArtRole": "true",
      "commentRole": "true",
      "podcastRole": "true",
      "streamRole": "true",
      "jukeboxRole": "true",
      "shareRole": "false"
    }
  }
}
{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "user": {
      "folder": [
          1,
          3
      ],
      "username": "sindre",
      "email": "sindre@activeobjects.no",
      "scrobblingEnabled": "true",
      "adminRole": "false",
      "settingsRole": "true",
      "downloadRole": "true",
      "uploadRole": "false",
      "playlistRole": "true",
      "coverArtRole": "true",
      "commentRole": "true",
      "podcastRole": "true",
      "streamRole": "true",
      "jukeboxRole": "true",
      "shareRole": "false"
    }
  }
}
FieldTypeReq.OpenS.Details
useruserYesThe user

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

Result

A subsonic-response element with a nested users element on success.

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "users": {
      "user": [
        {
          "folder": [
              1,
              3
          ],
          "username": "sindre",
          "email": "sindre@activeobjects.no",
          "scrobblingEnabled": "true",
          "adminRole": "false",
          "settingsRole": "true",
          "downloadRole": "true",
          "uploadRole": "false",
          "playlistRole": "true",
          "coverArtRole": "true",
          "commentRole": "true",
          "podcastRole": "true",
          "streamRole": "true",
          "jukeboxRole": "true",
          "shareRole": "false"
        }
      ]
    }
  }
}
{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "users": {
      "user": [
        {
          "folder": [
              1,
              3
          ],
          "username": "sindre",
          "email": "sindre@activeobjects.no",
          "scrobblingEnabled": "true",
          "adminRole": "false",
          "settingsRole": "true",
          "downloadRole": "true",
          "uploadRole": "false",
          "playlistRole": "true",
          "coverArtRole": "true",
          "commentRole": "true",
          "podcastRole": "true",
          "streamRole": "true",
          "jukeboxRole": "true",
          "shareRole": "false"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
usersusersYesThe users

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

ParameterReq.OpenS.DefaultComment
idYesThe video ID.

Example

Result

A subsonic-response element with a nested videoInfo element on success.

// TODO
// TODO
FieldTypeReq.OpenS.Details
videoInfovideoInfoYesThe song

61 - getVideos

Returns all video files.

http://your-server/rest/getVideos Since 1.8.0

Returns all video files.

Parameters

Takes no extra parameters.

Example

Result

A subsonic-response element with a nested videos element on success.

// TODO
// TODO
FieldTypeReq.OpenS.Details
videosvideosYesThe videos

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

ParameterReq.OpenS.DefaultComment
idYesA string which uniquely identifies the media file to stream.
bitRateNoIf 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
audioTrackNoThe ID of the audio track to use. SeegetVideoInfo for how to get the list of available audio tracks for a video.

Example

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

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

ParameterReq.OpenS.DefaultComment
actionYesThe 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
indexNoUsed by skip and remove. Zero-based index of the song to skip to or remove.
offsetNo(Since 1.7.0) Used by skip. Start playing this many seconds into the track.
idNoUsed 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.)
gainNoUsed by setGain to control the playback volume. A float value between 0.0 and 1.0.

Example

Result

A subsonic-response element with a nested :

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "jukeboxStatus": {
      "currentIndex": 7,
      "playing": true,
      "gain": 0.9,
      "position": 67
    }
  }
}
{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "jukeboxPlaylist": {
      "currentIndex": 7,
      "playing": true,
      "gain": 0.9,
      "position": 67,
      "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"
        }
      ]
    }
  }
}
{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "jukeboxStatus": {
      "currentIndex": 7,
      "playing": true,
      "gain": 0.9,
      "position": 67
    }
  }
}
{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "jukeboxPlaylist": {
      "currentIndex": 7,
      "playing": true,
      "gain": 0.9,
      "position": 67,
      "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"
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
jukeboxStatusjukeboxstatusYesThe jukeboxstatus
jukeboxPlaylistjukeboxPlaylistYesThe jukeboxstatus

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

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

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"
  }
}

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

ParameterReq.OpenS.DefaultComment
idNoID of a song in the play queue. Use one id parameter for each song in the play queue.
currentNoThe ID of the current playing song.
positionNoThe position in milliseconds within the currently playing song.

Example

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

ParameterReq.OpenS.DefaultComment
idYesA string which uniquely identifies the file to scrobble.
timeNo(Since 1.8.0) The time (in milliseconds since 1 Jan 1970) at which the song was listened to.
submissionNoTrueWhether this is a “submission” or a “now playing” notification.

Example

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"
  }
}

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

ParameterReq.OpenS.DefaultComment
artistNoArtist to search for.
albumNoAlbum to searh for.
titleNoSong title to search for.
anyNoSearches all fields.
countNo20Maximum number of results to return.
offsetNo0Search result offset. Used for paging.
newerThanNoOnly return matches that are newer than this. Given as milliseconds since 1970.

Example

Result

A subsonic-response element with a nested searchResult element on success.

// TODO
// TODO
FieldTypeReq.OpenS.Details
searchResultsearchResultYesThe result

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

ParameterReq.OpenS.DefaultComment
queryYesSearch query.
artistCountNo20Maximum number of artists to return.
artistOffsetNo0Search result offset for artists. Used for paging.
albumCountNo20Maximum number of albums to return.
albumOffsetNo0Search result offset for albums. Used for paging.
songCountNo20Maximum number of songs to return.
songOffsetNo0Search result offset for songs. Used for paging.
musicFolderIdNo(Since 1.12.0) Only return results from the music folder with the given ID. See getMusicFolders.

Example

Result

A subsonic-response element with a nested searchResult2 element on success.

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "searchResult2": {
      "artist": [
        {
          "id": "100000002",
          "name": "Synthetic",
          "coverArt": "ar-100000002",
          "albumCount": 1,
          "starred": "2021-02-22T05:54:18Z"
        }
      ],
      "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": "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,
          "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",
    "searchResult2": {
      "artist": [
        {
          "id": "100000002",
          "name": "Synthetic",
          "coverArt": "ar-100000002",
          "albumCount": 1,
          "starred": "2021-02-22T05:54:18Z"
        }
      ],
      "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": "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,
          "discNumber": 1,
          "created": "2023-03-14T17:51:22.112827504Z",
          "albumId": "e8a0685e3f3ec6f251649af2b58b8617",
          "artistId": "97e0398acf63f9fb930d7d4ce209a52b",
          "type": "music",
          "isVideo": false
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
searchResult2searchResult2YesThe result

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

ParameterRequ.OpenS.DefaultComment
queryYesSee below*Search query.
artistCountNo20Maximum number of artists to return.
artistOffsetNo0Search result offset for artists. Used for paging.
albumCountNo20Maximum number of albums to return.
albumOffsetNo0Search result offset for albums. Used for paging.
songCountNo20Maximum number of songs to return.
songOffsetNo0Search result offset for songs. Used for paging.
musicFolderIdNo(Since 1.12.0) Only return results from music folder with the given ID. See getMusicFolders.

Example

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
        }
      ]
    }
  }
}
FieldTypeReq.OpenS.Details
searchResult3searchResult3YesThe result of the search

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

ParameterReq.OpenS.DefaultComment
idYesA string which uniquely identifies the file (song) or folder (album/artist) to rate.
ratingYesThe rating between 1 and 5 (inclusive), or 0 to remove the rating.

Example

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

ParameterReq.OpenS.DefaultComment
idNoThe ID of the file (song) or folder (album/artist) to star. Multiple parameters allowed.
albumIdNoThe 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.
artistIdNoThe 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

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"
  }
}

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

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
    }
  }
}
FieldTypeReq.OpenS.Details
scanStatusscanStatusYesThe status of the scan

74 - stream

Streams a given media file.

http://your-server/rest/stream Since 1.0.0

Streams a given media file.

Parameters

ParameterReq.OpenS.DefaultComment
idYesA string which uniquely identifies the file to stream. Obtained by calls to getMusicDirectory.
maxBitRateNo(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.
formatNo(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.
timeOffsetNoNo / YesBy 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.
sizeNo(Since 1.6.0) Only applicable to video streaming. Requested video size specified as WxH, for instance “640x480”.
estimateContentLengthNofalse(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.
convertedNofalse(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

Result

Returns binary data on success, or an XML document on error (in which case the HTTP content type will start with “text/xml”).

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

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.
FieldTypeReq.OpenS.Details
tokenInfotokenInfoYesYesInformation about the token

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

ParameterReq.OpenS.DefaultComment
idNoThe ID of the file (song) or folder (album/artist) to unstar. Multiple parameters allowed.
albumIdNoThe 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.
artistIdNoThe 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

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

ParameterReq.OpenS.DefaultComment
idYesThe ID of the station.
streamUrlYesThe stream URL for the station.
nameYesThe user-defined name for the station.
homepageUrlNoThe home page URL for the station.

Example

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

ParameterReq.OpenS.DefaultComment
playlistIdYesThe playlist ID.
nameNoThe human-readable name of the playlist.
commentNoThe playlist comment.
publicNotrue if the playlist should be visible to all users, false otherwise.
songIdToAddNoAdd this song with this ID to the playlist. Multiple parameters allowed.
songIndexToRemoveNoRemove the song at this position in the playlist. Multiple parameters allowed.

Example

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

ParameterReq.OpenS.DefaultComment
idYesID of the share to update.
descriptionNoA user-defined description that will be displayed to people visiting the shared media.
expiresNoThe time at which the share expires. Given as milliseconds since 1970, or zero to remove the expiration.

Example

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"
  }
}

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

ParameterReq.OpenS.DefaultComment
usernameYesThe name of the user.
passwordNoThe password of the user, either in clear text of hex-encoded (see above).
emailNoThe email address of the user.
ldapAuthenticatedNoWhether the user is authenicated in LDAP.
adminRoleNoWhether the user is administrator.
settingsRoleNoWhether the user is allowed to change personal settings and password.
streamRoleNoWhether the user is allowed to play files.
jukeboxRoleNoWhether the user is allowed to play files in jukebox mode.
downloadRoleNoWhether the user is allowed to download files.
uploadRoleNoWhether the user is allowed to upload files.
coverArtRoleNoWhether the user is allowed to change cover art and tags.
commentRoleNoWhether the user is allowed to create and edit comments and ratings.
podcastRoleNoWhether the user is allowed to administrate Podcasts.
shareRoleNoWhether the user is allowed to share files with anyone.
videoConversionRoleNofalse(Since 1.15.0) Whether the user is allowed to start video conversions.
musicFolderIdNo(Since 1.12.0) IDs of the music folders the user is allowed access to. Include the parameter once for each folder.
maxBitRateNo(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

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"
  }
}