Endpoints
Playlist endpoint reference.
Query Parameters
Preferred language as a BCP 47 language tag.
Comma-separated relationships to include. Nested includes use dot notation and may be up to three levels deep from the root resource.
Limit an included relationship. Replace {resource}:{relationship} with the singular resource type and relationship name, for example limit[album:tracks].
Sort an included relationship. Replace {resource}:{relationship} with the singular resource type and relationship name, for example sort[album:tracks]. Supports name, dateAdded, and minus-prefixed descending variants. Song and album relationships also support releaseDate and -releaseDate.
Comma-separated playlist fields.
Comma-separated song fields.
Maximum number of resources to return. The usual maximum is 100.
Number of resources to skip.
Sort field. Supports name, dateAdded, and minus-prefixed descending variants. dateAdded is the date the resource was added to the server. Song and album result sets also support releaseDate and -releaseDate.
Response Body
application/json
application/json
curl -X GET "https://example.com/playlists?lang=en-US&include=albums&limit%5B%7Bresource%7D%3A%7Brelationship%7D%5D=10&sort%5B%7Bresource%7D%3A%7Brelationship%7D%5D=name&fields%5Bplaylist%5D=name%2Cdescription&fields%5Bsong%5D=name%2CartworkUrl&sort=name"{ "data": [ { "id": "123456789", "type": "playlist", "attributes": { "name": "string", "trackCount": 0, "curatorName": "string", "artworkUrl": "string", "description": "string" }, "relationships": { "tracks": { "data": [ { "id": "123456789", "type": "song", "attributes": { "name": "string", "files": { "preferred": { "id": "string", "lossless": true, "mimeType": "audio/flac", "sizeBytes": 0, "durationMs": 0, "streamUrl": "http://example.com", "downloadUrl": "http://example.com", "codec": "flac", "bitrateKbps": 0, "sampleRateHz": 0, "channels": 1 }, "alternatives": [ { "id": "string", "lossless": true, "mimeType": "audio/flac", "sizeBytes": 0, "durationMs": 0, "streamUrl": "http://example.com", "downloadUrl": "http://example.com", "codec": "flac", "bitrateKbps": 0, "sampleRateHz": 0, "channels": 1 } ] }, "albumName": "string", "artistName": "string", "isrc": "string", "artworkUrl": "string", "trackNumber": 1, "discNumber": 1, "genres": [ "string" ], "releaseDate": "string", "durationMs": 0, "lyrics": { "lang": "en-US", "text": "string", "ttml": "string" } }, "relationships": { "albums": { "data": [ { "id": "123456789", "type": "album", "attributes": { "name": "string", "trackCount": 0, "artistName": "string", "artworkUrl": "string", "upc": "string", "genres": [ "string" ], "releaseDate": "string" }, "relationships": { "tracks": { "data": [], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "artists": { "data": [ { "attributes": {}, "relationships": {} } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "artists": { "data": [ { "id": "123456789", "type": "artist", "attributes": { "name": "string", "artworkUrl": "string" }, "relationships": { "tracks": { "data": [], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "albums": { "data": [ { "attributes": {}, "relationships": {} } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 }}{ "error": { "status": 100, "message": "string", "details": [ { "message": "string", "param": "string", "value": null } ], "requestId": "string" }}Query Parameters
Preferred language as a BCP 47 language tag.
Comma-separated ids. The order of returned resources should match the request order. Maximum 100 ids.
Comma-separated relationships to include. Nested includes use dot notation and may be up to three levels deep from the root resource.
Limit an included relationship. Replace {resource}:{relationship} with the singular resource type and relationship name, for example limit[album:tracks].
Sort an included relationship. Replace {resource}:{relationship} with the singular resource type and relationship name, for example sort[album:tracks]. Supports name, dateAdded, and minus-prefixed descending variants. Song and album relationships also support releaseDate and -releaseDate.
Comma-separated playlist fields.
Comma-separated song fields.
Response Body
application/json
application/json
curl -X GET "https://example.com/playlists/lookup?lang=en-US&ids=1%2Comm%3Asong%3A2&include=albums&limit%5B%7Bresource%7D%3A%7Brelationship%7D%5D=10&sort%5B%7Bresource%7D%3A%7Brelationship%7D%5D=name&fields%5Bplaylist%5D=name%2Cdescription&fields%5Bsong%5D=name%2CartworkUrl"{ "data": [ { "id": "123456789", "type": "playlist", "attributes": { "name": "string", "trackCount": 0, "curatorName": "string", "artworkUrl": "string", "description": "string" }, "relationships": { "tracks": { "data": [ { "id": "123456789", "type": "song", "attributes": { "name": "string", "files": { "preferred": { "id": "string", "lossless": true, "mimeType": "audio/flac", "sizeBytes": 0, "durationMs": 0, "streamUrl": "http://example.com", "downloadUrl": "http://example.com", "codec": "flac", "bitrateKbps": 0, "sampleRateHz": 0, "channels": 1 }, "alternatives": [ { "id": "string", "lossless": true, "mimeType": "audio/flac", "sizeBytes": 0, "durationMs": 0, "streamUrl": "http://example.com", "downloadUrl": "http://example.com", "codec": "flac", "bitrateKbps": 0, "sampleRateHz": 0, "channels": 1 } ] }, "albumName": "string", "artistName": "string", "isrc": "string", "artworkUrl": "string", "trackNumber": 1, "discNumber": 1, "genres": [ "string" ], "releaseDate": "string", "durationMs": 0, "lyrics": { "lang": "en-US", "text": "string", "ttml": "string" } }, "relationships": { "albums": { "data": [ { "id": "123456789", "type": "album", "attributes": { "name": "string", "trackCount": 0, "artistName": "string", "artworkUrl": "string", "upc": "string", "genres": [ "string" ], "releaseDate": "string" }, "relationships": { "tracks": { "data": [], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "artists": { "data": [ { "attributes": {}, "relationships": {} } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "artists": { "data": [ { "id": "123456789", "type": "artist", "attributes": { "name": "string", "artworkUrl": "string" }, "relationships": { "tracks": { "data": [], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "albums": { "data": [ { "attributes": {}, "relationships": {} } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ]}{ "error": { "status": 100, "message": "string", "details": [ { "message": "string", "param": "string", "value": null } ], "requestId": "string" }}Path Parameters
Resource id. This can be a local id or an OpenMusicMetadata id like omm:song:123456789.
Query Parameters
Preferred language as a BCP 47 language tag.
Comma-separated relationships to include. Nested includes use dot notation and may be up to three levels deep from the root resource.
Limit an included relationship. Replace {resource}:{relationship} with the singular resource type and relationship name, for example limit[album:tracks].
Sort an included relationship. Replace {resource}:{relationship} with the singular resource type and relationship name, for example sort[album:tracks]. Supports name, dateAdded, and minus-prefixed descending variants. Song and album relationships also support releaseDate and -releaseDate.
Comma-separated playlist fields.
Comma-separated song fields.
Response Body
application/json
application/json
curl -X GET "https://example.com/playlist/123456789?lang=en-US&include=albums&limit%5B%7Bresource%7D%3A%7Brelationship%7D%5D=10&sort%5B%7Bresource%7D%3A%7Brelationship%7D%5D=name&fields%5Bplaylist%5D=name%2Cdescription&fields%5Bsong%5D=name%2CartworkUrl"{ "data": { "id": "123456789", "type": "playlist", "attributes": { "name": "string", "trackCount": 0, "curatorName": "string", "artworkUrl": "string", "description": "string" }, "relationships": { "tracks": { "data": [ { "id": "123456789", "type": "song", "attributes": { "name": "string", "files": { "preferred": { "id": "string", "lossless": true, "mimeType": "audio/flac", "sizeBytes": 0, "durationMs": 0, "streamUrl": "http://example.com", "downloadUrl": "http://example.com", "codec": "flac", "bitrateKbps": 0, "sampleRateHz": 0, "channels": 1 }, "alternatives": [ { "id": "string", "lossless": true, "mimeType": "audio/flac", "sizeBytes": 0, "durationMs": 0, "streamUrl": "http://example.com", "downloadUrl": "http://example.com", "codec": "flac", "bitrateKbps": 0, "sampleRateHz": 0, "channels": 1 } ] }, "albumName": "string", "artistName": "string", "isrc": "string", "artworkUrl": "string", "trackNumber": 1, "discNumber": 1, "genres": [ "string" ], "releaseDate": "string", "durationMs": 0, "lyrics": { "lang": "en-US", "text": "string", "ttml": "string" } }, "relationships": { "albums": { "data": [ { "id": "123456789", "type": "album", "attributes": { "name": "string", "trackCount": 0, "artistName": "string", "artworkUrl": "string", "upc": "string", "genres": [ "string" ], "releaseDate": "string" }, "relationships": { "tracks": { "data": [], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "artists": { "data": [ { "id": "123456789", "type": "artist", "attributes": {}, "relationships": { "tracks": {}, "albums": {} } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "artists": { "data": [ { "id": "123456789", "type": "artist", "attributes": { "name": "string", "artworkUrl": "string" }, "relationships": { "tracks": { "data": [], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "albums": { "data": [ { "id": "123456789", "type": "album", "attributes": { "genres": [] }, "relationships": { "tracks": {}, "artists": {} } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } }}{ "error": { "status": 100, "message": "string", "details": [ { "message": "string", "param": "string", "value": null } ], "requestId": "string" }}Path Parameters
Resource id. This can be a local id or an OpenMusicMetadata id like omm:song:123456789.
Query Parameters
Preferred language as a BCP 47 language tag.
Comma-separated song fields.
Maximum number of resources to return. The usual maximum is 100.
Number of resources to skip.
Sort field. Supports name, dateAdded, and minus-prefixed descending variants. dateAdded is the date the resource was added to the server. Song and album result sets also support releaseDate and -releaseDate.
Response Body
application/json
application/json
curl -X GET "https://example.com/playlist/123456789/rel/tracks?lang=en-US&fields%5Bsong%5D=name%2CartworkUrl&sort=name"{ "data": [ { "id": "123456789", "type": "song", "attributes": { "name": "string", "files": { "preferred": { "id": "string", "lossless": true, "mimeType": "audio/flac", "sizeBytes": 0, "durationMs": 0, "streamUrl": "http://example.com", "downloadUrl": "http://example.com", "codec": "flac", "bitrateKbps": 0, "sampleRateHz": 0, "channels": 1 }, "alternatives": [ { "id": "string", "lossless": true, "mimeType": "audio/flac", "sizeBytes": 0, "durationMs": 0, "streamUrl": "http://example.com", "downloadUrl": "http://example.com", "codec": "flac", "bitrateKbps": 0, "sampleRateHz": 0, "channels": 1 } ] }, "albumName": "string", "artistName": "string", "isrc": "string", "artworkUrl": "string", "trackNumber": 1, "discNumber": 1, "genres": [ "string" ], "releaseDate": "string", "durationMs": 0, "lyrics": { "lang": "en-US", "text": "string", "ttml": "string" } }, "relationships": { "albums": { "data": [ { "id": "123456789", "type": "album", "attributes": { "name": "string", "trackCount": 0, "artistName": "string", "artworkUrl": "string", "upc": "string", "genres": [ "string" ], "releaseDate": "string" }, "relationships": { "tracks": { "data": [], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "artists": { "data": [ { "id": "123456789", "type": "artist", "attributes": { "name": "string", "artworkUrl": "string" }, "relationships": { "tracks": { "data": [], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "albums": { "data": [], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "artists": { "data": [ { "id": "123456789", "type": "artist", "attributes": { "name": "string", "artworkUrl": "string" }, "relationships": { "tracks": { "data": [], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "albums": { "data": [ { "id": "123456789", "type": "album", "attributes": { "name": "string", "trackCount": 0, "artistName": "string", "artworkUrl": "string", "upc": "string", "genres": [ "string" ], "releaseDate": "string" }, "relationships": { "tracks": { "data": [], "meta": { "limit": 0, "offset": 0, "total": 0 } }, "artists": { "data": [], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 } } } } ], "meta": { "limit": 0, "offset": 0, "total": 0 }}{ "error": { "status": 100, "message": "string", "details": [ { "message": "string", "param": "string", "value": null } ], "requestId": "string" }}