Collections on OpenSubsonic

collection

Mon, 01 Jan 0001 00:00:00 +0000

Does not contain the items in the collection, look at collectionWithItems instead.

{
 "id": "800000075",
 "name": "testcollection",
 "owner": "user",
 "public": true,
 "created": "2026-03-16T03:18:41+00:00",
 "changed": "2026-03-16T03:18:41+00:00",
 "itemCount": 3,
 "readonly": true,
 "validUntil": "2026-03-23T03:18:41+00:00"
}

Field	Type	Req.	Details
`id`	`string`	Yes	Id of the collection
`name`	`string`	Yes	Name of the collection
`comment`	`string`	No	A commnet
`owner`	`string`	No	Owner of the collection
`public`	`boolean`	No	Is the collection public
`itemCount`	`int`	Yes	number of items
`created`	`string`	Yes	Creation date [ISO 8601]
`changed`	`string`	Yes	Last changed date [ISO 8601]
`allowedUser`	Array of `string`	No	A list of allowed usernames
`readonly`	`boolean`	No	If true the collection cannot be edited by the current user
`validUntil`	`string`	No	Date the collection contents are considered valid until [ISO 8601]

When readonly is true, clients should hide or disable UI actions that modify the collection. The value should reflect the current authenticated user’s access level. When omitted, clients should assume the collection is editable (false).

collectionItem

Mon, 01 Jan 0001 00:00:00 +0000

An item in a collection is a wrapper around one of the following types:

{
 "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",
 "isrc": [
 "USSM18300073",
 "DELV42300297",
 "DEE868300011",
 "DEE868300007"
 ],
 "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"
 ],
 "explicitStatus": "explicit",
 "replayGain": {
 "trackGain": 0.1,
 "albumGain": 1.1,
 "trackPeak": 9.2,
 "albumPeak": 9,
 "baseGain": 0
 },
 "works": [
 {
 "name": "Symphony No. 5 in C minor, Op. 67",
 "musicBrainzId": "d03bff61-26fc-301b-98ac-4d8e85771cbc"
 }
 ],
 "movements": [
 {
 "name": "Andante con moto",
 "number": 2,
 "count": 4
 }
 ],
 "groupings": ["Soundtrack", "Live"]
 }
}

{
 "album": {
 "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
 "name": "8-bit lagerfeuer",
 "version": "Deluxe Edition",
 "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,
 "played": "2023-03-28T00:45:13Z",
 "userRating": 4,
 "recordLabels": [
 {
 "name": "Sony"
 }
 ],
 "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",
 "releaseTypes": [
 "Album",
 "Remixes"
 ],
 "moods": [
 "slow",
 "cool"
 ],
 "sortName": "lagerfeuer (8-bit)",
 "originalReleaseDate": {
 "year": 2001,
 "month": 3,
 "day": 10
 },
 "releaseDate": {
 "year": 2001,
 "month": 3,
 "day": 10
 },
 "isCompilation": false,
 "explicitStatus": "explicit",
 "discTitles": [
 {
 "disc": 0,
 "title": "Disc 0 title"
 "coverArt": "42"
 },
 {
 "disc": 2,
 "title": "Disc 1 title"
 "coverArt": "6547"
 }
 ]
 }
}

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

{
 "playlist": {
 "id": "800000075",
 "name": "testplaylist",
 "owner": "user",
 "public": true,
 "created": "2023-03-16T03:18:41+00:00",
 "changed": "2023-03-16T03:18:41+00:00",
 "songCount": 1,
 "duration": 304,
 "readonly": true,
 "validUntil": "2023-03-23T03:18:41+00:00"
 }
}

{
 "genre": {
 "value": "vaporwave",
 "songCount": 6,
 "albumCount": 1
 }
}

collectionItemID

Mon, 01 Jan 0001 00:00:00 +0000

Depending on the item type, either id or name must be provided. For most types, id is the natural choice, but some types (e.g. Genre) don’t have it, so name should be used.

{
 "type": "song",
 "id": "20"
}

{
 "type": "album",
 "id": "30"
}

{
 "type": "genre",
 "name": "vaporwave"
}

Field	Type	Req.	Details
`type`	`string`	Yes	One of: song, album, artist, playlist
`id`	`string`	No	ID of the item, where applicable
`name`	`string`	No	Name of the item, where applicable

collectionWithItems

Mon, 01 Jan 0001 00:00:00 +0000

{
 "id": "800000075",
 "name": "testcollection",
 "owner": "user",
 "public": true,
 "created": "2026-03-16T03:18:41+00:00",
 "changed": "2026-03-16T03:18:41+00:00",
 "itemCount": 3,
 "readonly": true,
 "validUntil": "2026-03-23T03:18:41+00:00",
 "items": [
 {
 "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"
 }
 },
 {
 "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"
 }
 },
 {
 "genre": {
 "value": "vaporwave",
 "songCount": 6,
 "albumCount": 1
 }
 }
 ]
}

Field	Type	Req.	Details
`id`	`string`	Yes	Id of the collection
`name`	`string`	Yes	Name of the collection
`comment`	`string`	No	A commnet
`owner`	`string`	No	Owner of the collection
`public`	`boolean`	No	Is the collection public
`itemCount`	`int`	Yes	number of items
`created`	`string`	Yes	Creation date [ISO 8601]
`changed`	`string`	Yes	Last changed date [ISO 8601]
`allowedUser`	Array of `string`	No	A list of allowed usernames
`readonly`	`boolean`	No	If true the collection cannot be edited by the current user
`validUntil`	`string`	No	Date the collection contents are considered valid until [ISO 8601]
`items`	Array of `collectionItem`	Yes	The list of items

When readonly is true, clients should hide or disable UI actions that modify the collection. This is useful for server-generated collections like smart collections, recommendations, or curated system lists. The value should reflect the current authenticated user’s access level. When omitted, clients should assume the collection is editable (false).

createCollection

Mon, 01 Jan 0001 00:00:00 +0000

http://your-server/rest/createCollection

Creates a collection. This endpoint must be accessed using an HTTP POST request.

Request Body

The request payload should be provided in the body as a JSON object.

Parameter	Req.	Default	Comment
`name`	Yes		The human-readable name of the collection.
`comment`	No		The collection comment.
`public`	No	`false`	`true` if the collection should be visible to all users, `false` otherwise.
`items`	No		A list of collectionItemID objects.

Example request

POST http://your-server/rest/createCollection.view?u=demo&p=demo&v=1.16.1&c=AwesomeClientName&f=json

{
 "name": "test collection",
 "comment": "this is a collection",
 "items": [
 {
 "type": "song",
 "id": "300000060"
 },
 {
 "type": "album",
 "id": "200000021"
 },
 {
 "type": "genre",
 "name": "vaporwave"
 }
 ]
}

Result

A subsonic-response element with a top-level collection object on success.

deleteCollection

Mon, 01 Jan 0001 00:00:00 +0000

http://your-server/rest/deleteCollection

Deletes a collection.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			ID of the collection to delete, as obtained by `getCollections`.

Example

http://your-server/rest/deleteCollection.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

An empty subsonic-response element on success.

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true
 }
}

getCollection

Mon, 01 Jan 0001 00:00:00 +0000

http://your-server/rest/getCollection

Returns a collection with the items it contains.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			ID of the collection to return, as obtained by `getCollections`.

Example

http://your-server/rest/getCollection.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

A subsonic-response element with a top-level collection object of type collectionWithItems

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "collection": {
 "id": "800000075",
 "name": "testcreate",
 "comment" "this is a collection",
 "owner": "user",
 "public": true,
 "itemCount": 3,
 "created": "2023-03-16T03:18:41+00:00",
 "changed": "2023-03-16T03:18:41+00:00",
 "items": [
 {
 "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"
 }
 },
 {
 "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"
 }
 },
 {
 "genre": {
 "value": "vaporwave",
 "songCount": 6,
 "albumCount": 1
 }
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`collection`	`collectionWithItems`	Yes		The collection

getCollections

Mon, 01 Jan 0001 00:00:00 +0000

http://your-server/rest/getCollections

Returns all collections a user has access to.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`username`	No			If specified, return collections for this user rather than for the authenticated user. The authenticated user must have admin role if this parameter is used.

Example

http://your-server/rest/getCollections.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

A subsonic-response element with a top-level collections array of collection elements on success.

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "collections": [
 {
 "id": "800000075",
 "name": "testcollection",
 "owner": "user",
 "public": true,
 "created": "2026-03-16T03:18:41+00:00",
 "changed": "2026-03-16T03:18:41+00:00",
 "itemCount": 3,
 "readonly": true,
 "validUntil": "2026-03-23T03:18:41+00:00"
 },
 {
 "id": "800000076",
 "name": "testcollection2",
 "comment" "this is another collection",
 "owner": "user",
 "public": false,
 "itemCount": 17,
 "created": "2026-03-16T03:18:41+00:00",
 "changed": "2026-03-16T03:18:41+00:00",
 "readonly": true
 }
 ]
 }
}

Field	Type	Req.	OpenS.	Details
`collections`	Array of `collection`	Yes		The collections

updateCollection

Mon, 01 Jan 0001 00:00:00 +0000

http://your-server/rest/updateCollection

Updates a collection. Only the owner of a collection is allowed to update it. This endpoint must be accessed using an HTTP POST request. Only the fields specified in the request payload will have an effect on a collection.

Request Body

The request payload should be provided in the body as a JSON object.

Parameter	Req.	Comment
`collectionId`	Yes	The collection ID.
`name`	No	The human-readable name of the collection.
`comment`	No	The collection comment.
`public`	No	`true` if the collection should be visible to all users, `false` otherwise.
`add`	No	Add the specified items to the collection. The payload is an array of collectionItemID objects. Items are appended to the tail of the collection.
`move`	No	Move items from the original position to a new one in the collection. The original range is specified by the `fromStart` (inclusive) and `fromEnd` (exclusive) positions. The first item in the range moves to the position specified by `to`
`remove`	No	Remove the items at the specified positions from the collection. The payload is an array of integer indices.

Only one of add, move, and remove can be non-empty in a single request.