PrivatePlaylistsAPI

class minim.api.tidal.PrivatePlaylistsAPI(client: APIClient, /)

Bases: PrivateTIDALResourceAPI

Playlists API endpoints for the private TIDAL API.

Important

This class is managed by PrivateTIDALAPIClient and should not be instantiated directly.

Parameters:

clientminim.api._shared.APIClient

API client instance used to make HTTP requests.

Methods

add_playlist_items	Add items to a playlist.
create_folder	Create a playlist folder.
create_playlist	Create a playlist.
delete_folders	Delete playlist folders.
delete_playlists	Delete playlists.
follow_playlists	Add playlists to a user's collection.
get_followed_playlists	Get TIDAL catalog information for editorial playlists in a user's collection.
get_my_folder	Get TIDAL catalog information for playlists in a playlist folder in the current user's collection.
get_my_folders_and_playlists	Get TIDAL catalog information for all playlist folders and playlists in the current user's collection.
get_my_playlists	Get TIDAL catalog information for playlists in the current user's collection.
get_playlist	Get TIDAL catalog information for a playlist.
get_playlist_items	Get TIDAL catalog information for tracks and videos in a playlist.
get_playlist_recommended_tracks	Get TIDAL catalog information for tracks recommended based on a playlist.
get_user_created_playlists	Get TIDAL catalog information for user-created playlists in a user's collection.
get_user_playlists	Get TIDAL catalog information for editorial and user-created playlists in a user's collection.
get_user_public_playlists	Get TIDAL catalog information for public playlists in a user's collection.
move_playlists	Move playlists in the current user's collection.
remove_playlist_items	Remove items from a playlist.
reorder_playlist_items	Reorder items in a playlist.
replace_playlist_item	Replace an item in a playlist with another item.
set_playlist_visibility	Set the visibility of a playlist.
unfollow_playlists	Remove playlists from a user's collection.
update_playlist_details	Update the details of a playlist.

add_playlist_items(playlist_uuid: str, /, country_code: str | None = None, *, item_ids: int | str | Collection[int | str] | None = None, from_album_id: int | str | None = None, from_playlist_uuid: str | None = None, on_duplicate: str | None = None) → None

Add items to a playlist.

User authentication

Required

User authentication

Access and manage the user’s collection.

Important

Exactly one of item_ids, from_album_id, or from_playlist_uuid must be provided.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "0ae80812-f8d6-4fc4-90ea-b2df4ecc3861".

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

item_idsint, str, or Collection[int | str]; keyword-only; optional

TIDAL IDs of the tracks and videos.

Examples: 46369325, "75413016", "46369325,75413016", [46369325, "75413016"].

from_album_idint or str; keyword-only; optional

TIDAL ID of the album to add tracks and videos from.

Examples: 46369321, "251380836".

from_playlist_uuidstr; keyword-only; optional

UUID of the TIDAL playlist to add tracks and videos from.

Example: "0ae80812-f8d6-4fc4-90ea-b2df4ecc3861".

on_duplicatestr; keyword-only; optional

Behavior when the items to be added are already in the playlist.

Valid values: "ADD", "FAIL", "SKIP".

create_folder(name: str, *, folder_uuid: str | None = None) → dict[str, Any]

Create a playlist folder.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

namestr

Playlist folder name.

Example: "My New Playlist Folder Title".

folder_uuidstr; keyword-only; optional

UUID of TIDAL playlist folder to add the new playlist folder to. Use "root" or leave blank to target the top-level “Playlists” folder.

Returns:

folderdict[str, Any]

TIDAL metadata for the newly created playlist folder.

Sample response

{
  "addedAt": <str>,
  "data": {
    "createdAt": <str>,
    "id": <str>,
    "itemType": "FOLDER",
    "lastModifiedAt": <str>,
    "name": <str>,
    "totalNumberOfItems": <int>,
    "trn": <str>
  },
  "itemType": "FOLDER",
  "lastModifiedAt": <str>,
  "name": <str>,
  "parent": {
    "id": <str>,
    "name": <str>
  },
  "trn": <str>
}

create_playlist(name: str, *, description: str | None = None, public: bool | None = None, folder_uuid: str | None = None) → dict[str, Any]

Create a playlist.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

namestr

Playlist name.

Example: "My New Playlist Title".

descriptionstr; keyword-only; optional

Playlist description.

publicbool; keyword-only; optional

Whether the playlist is displayed on the user’s profile.

API default: False.

folder_uuidstr; keyword-only; optional

UUID of TIDAL playlist folder to add the new playlist to. Use "root" or leave blank to target the top-level “Playlists” folder.

Returns:

playlistdict[str, Any]

TIDAL metadata for the newly created playlist.

Sample response

{
  "addedAt": <str>,
  "data": {
    "contentBehavior": <str>,
    "created": <str>,
    "creator": {
      "id": <int>,
      "name": <str>,
      "picture": <str>,
      "type": "USER"
    },
    "curators": [
      {
        "handle": <str>,
        "id": <int>,
        "name": <str>,
        "picture": <str>
      }
    ],
    "customImageUrl": <str>,
    "description": <str>,
    "duration": 0,
    "image": <str>,
    "itemType": "PLAYLIST",
    "lastItemAddedAt": <str>,
    "lastUpdated": <str>,
    "numberOfTracks": 0,
    "numberOfVideos": 0,
    "promotedArtists": [
      {
        "handle": <str>,
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "type": <str>
      }
    ],
    "sharingLevel": <str>,
    "source": "DEFAULT",
    "squareImage": <str>,
    "status": "READY",
    "title": <str>,
    "trn": <str>,
    "type": "USER",
    "url": <str>,
    "uuid": <str>
  },
  "itemType": "PLAYLIST",
  "lastModifiedAt": <str>,
  "name": <str>,
  "parent": {
    "id": <str>,
    "name": <str>
  },
  "trn": <str>
}

delete_folders(folder_uuids: str | Collection[str], /) → None

Delete playlist folders.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

folder_uuidsstr or Collection[str]; positional-only

UUIDs or TIDAL resource names of the playlist folders.

Examples:

• "trn:folder:618ff600-dce1-4326-8724-9f0a51f63439"

• "trn:folder:618ff600-dce1-4326-8724-9f0a51f63439,550e8400-e29b-41d4-a716-446655440000"

• ["trn:folder:618ff600-dce1-4326-8724-9f0a51f63439", "550e8400-e29b-41d4-a716-446655440000"]

delete_playlists(playlist_uuids: str | Collection[str], /) → None

Delete playlists.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

playlist_uuidsstr or Collection[str]; positional-only

UUIDs or TIDAL resource names of the playlists.

Examples:

• "trn:playlist:0ae80812-f8d6-4fc4-90ea-b2df4ecc3861"

• "trn:playlist:0ae80812-f8d6-4fc4-90ea-b2df4ecc3861,24c9cc46-2fcd-4afb-bcc6-d6c42315f32e"

• ["trn:playlist:0ae80812-f8d6-4fc4-90ea-b2df4ecc3861", "24c9cc46-2fcd-4afb-bcc6-d6c42315f32e"]

follow_playlists(playlist_uuids: str | Collection[str], /, *, user_id: int | str | None = None, country_code: str | None = None, folder_uuid: str | None = None, api_version: int = 2) → None

Add playlists to a user’s collection.

User authentication

Required

User authentication

Access user recommendations, and view and modify user’s collection.

Parameters:

playlist_uuidsstr or Collection[str]; positional-only; optional

Playlist UUIDs.

Examples:

• "0ae80812-f8d6-4fc4-90ea-b2df4ecc3861"

• "0ae80812-f8d6-4fc4-90ea-b2df4ecc3861,24c9cc46-2fcd-4afb-bcc6-d6c42315f32e"

• ["0ae80812-f8d6-4fc4-90ea-b2df4ecc3861", "24c9cc46-2fcd-4afb-bcc6-d6c42315f32e"]

user_idint or str; keyword-only; optional

TIDAL ID of the user. If not specified, the current user’s TIDAL ID is used. Only applicable when version is 1.

Example: "US".

folder_uuidstr; keyword-only; optional

UUID of the TIDAL playlist folder to add playlists to. Use "root" or leave blank to target the top-level “Playlists” folder. Only applicable when version is 2.

api_versionint; keyword-only; default: 2

Private TIDAL API version.

Valid values:

• 1 – Legacy POST /v1/users/{user_id}/favorites/playlists endpoint.

• 2 – Current PUT /v2/my-collection/playlists/folders/add-favorites endpoint.

get_followed_playlists(user_id: int | str | None = None, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None, sort_by: str | None = None, descending: bool | None = None) → dict[str, Any]

Get TIDAL catalog information for editorial playlists in a user’s collection.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

user_idint or str; positional-only; optional

TIDAL ID of the user. If not specified, the current user’s TIDAL ID is used.

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

limitint; keyword-only; optional

Maximum number of playlists to return.

Valid range: 1 to 100.

API default: 10.

offsetint; keyword-only; optional

Index of the first playlist to return. Use with limit to get the next batch of playlists.

Minimum value: 0.

API default: 0.

sort_bystr; keyword-only; optional

Field to sort the playlists by.

Valid values:

• "DATE" - Date added.

• "NAME" - Playlist name.

API default: "DATE".

descendingbool; keyword-only; optional

Whether to sort in descending order.

API default: False.

Returns:

playlistsdict[str, Any]

Page of TIDAL metadata for the editorial playlists in the user’s collection.

Sample response

{
  "items": [
    {
      "created": <str>,
      "item": {
        "created": <str>,
        "creator": {
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": <str>
        },
        "customImageUrl": <str>,
        "description": <str>,
        "duration": <int>,
        "image": <str>,
        "lastItemAddedAt": <str>,
        "lastUpdated": <str>,
        "numberOfTracks": <int>,
        "numberOfVideos":<int>,
        "popularity": <int>,
        "promotedArtists": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": <str>
          }
        ],
        "publicPlaylist": <bool>,
        "squareImage": <str>,
        "title": <str>,
        "type": <str>,
        "url": <str>,
        "uuid": <str>
      }
    }
  ],
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>
}

get_my_folder(folder_uuid: str | None = None, /, *, cursor: str | None = None, limit: int = 50, playlist_types: str | Collection[str] | None = None, sort_by: str | None = None, descending: bool | None = None) → dict[str, Any]

Get TIDAL catalog information for playlists in a playlist folder in the current user’s collection.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

folder_uuidstr; positional-only; optional

UUID of TIDAL playlist folder to retrieve playlists from. Use "root" or leave blank to target the top-level “Playlists” folder.

limitint; keyword-only; default: 50

Maximum number of playlists to return.

Valid range: 1 to 50.

cursorstr; keyword-only; optional

Cursor for fetching the next page of results.

playlist_typesstr or Collection[str]; keyword-only; optional

Playlist types to return. If not specified, all playlists are returned.

Valid values:

• "FOLDER" – Playlist folders.

• "PLAYLIST" – All playlists.

• "FAVORITE_PLAYLIST" – Favorited playlists.

• "USER_PLAYLIST" – User-created playlists.

Examples: "USER_PLAYLIST", "FOLDER,USER_PLAYLIST", ["FOLDER", "USER_PLAYLIST"].

sort_bystr; keyword-only; optional

Field to sort the playlists by.

Valid values:

• "DATE" - Date added.

• "NAME" - Playlist name.

API default: "DATE".

descendingbool; keyword-only; optional

Whether to sort in descending order.

API default: False.

Returns:

playlistsdict[str, Any]

Page of TIDAL metadata for the playlists in the playlist folder in the current user’s collection.

Sample response

{
  "cursor": <str>,
  "items": [
    {
      "addedAt": <str>,
      "data": {
        "createdAt": <str>,
        "id": <str>,
        "itemType": "FOLDER",
        "lastModifiedAt": <str>,
        "name": <str>,
        "totalNumberOfItems": <int>,
        "trn": <str>,
      },
      "itemType": "FOLDER",
      "lastModifiedAt": <str>,
      "name": <str>,
      "parent": {
        "id": <str>,
        "name": <str>
      },
      "trn": <str>,
    },
    {
      "addedAt": <str>,
      "data": {
        "contentBehavior": <str>,
        "created": <str>,
        "creator": {
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": <str>
        },
        "curators": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>
          }
        ],
        "customImageUrl": <str>,
        "description": <str>,
        "duration": <int>,
        "image": <str>,
        "itemType": "PLAYLIST",
        "lastItemAddedAt": <str>,
        "lastUpdated": <str>,
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "promotedArtists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>
          }
        ],
        "sharingLevel": <str>,
        "source": <str>,
        "squareImage": <str>,
        "status": <str>,
        "title": <str>,
        "trn": <str>,
        "type": <str>,
        "url": <str>,
        "uuid": <str>
      },
      "itemType": "PLAYLIST",
      "lastModifiedAt": <str>,
      "name": <str>,
      "parent": {
        "id": <str>,
        "name": <str>
      },
      "trn": <str>
    }
  ],
  "lastModifiedAt": <str>,
  "totalNumberOfItems": <int>
}

get_my_folders_and_playlists(*, cursor: str | None = None, limit: int = 50, playlist_types: str | Collection[str] | None = None, sort_by: str | None = None, descending: bool | None = None) → dict[str, Any]

Get TIDAL catalog information for all playlist folders and playlists in the current user’s collection.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

limitint; keyword-only; default: 50

Maximum number of playlists to return.

Valid range: 1 to 50.

cursorstr; keyword-only; optional

Cursor for fetching the next page of results.

playlist_typesstr or Collection[str]; keyword-only; optional

Playlist types to return. If not specified, all playlists are returned.

Valid values:

• "FOLDER" – Playlist folders.

• "PLAYLIST" – All playlists.

• "FAVORITE_PLAYLIST" – Favorited playlists.

• "USER_PLAYLIST" – User-created playlists.

Examples: "USER_PLAYLIST", "FOLDER,USER_PLAYLIST", ["FOLDER", "USER_PLAYLIST"].

sort_bystr; keyword-only; optional

Field to sort the playlists by.

Valid values:

• "DATE" - Date added.

• "NAME" - Playlist name.

API default: "DATE".

descendingbool; keyword-only; optional

Whether to sort in descending order.

API default: False.

Returns:

playlistsdict[str, Any]

Page of TIDAL metadata for the playlist folders and playlists in the current user’s collection.

Sample response

{
  "cursor": <str>,
  "items": [
    {
      "addedAt": <str>,
      "data": {
        "createdAt": <str>,
        "id": <str>,
        "itemType": "FOLDER",
        "lastModifiedAt": <str>,
        "name": <str>,
        "totalNumberOfItems": <int>,
        "trn": <str>,
      },
      "itemType": "FOLDER",
      "lastModifiedAt": <str>,
      "name": <str>,
      "parent": {
        "id": <str>,
        "name": <str>
      },
      "trn": <str>,
    },
    {
      "addedAt": <str>,
      "data": {
        "contentBehavior": <str>,
        "created": <str>,
        "creator": {
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": <str>
        },
        "curators": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>
          }
        ],
        "customImageUrl": <str>,
        "description": <str>,
        "duration": <int>,
        "image": <str>,
        "itemType": "PLAYLIST",
        "lastItemAddedAt": <str>,
        "lastUpdated": <str>,
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "promotedArtists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>
          }
        ],
        "sharingLevel": <str>,
        "source": <str>,
        "squareImage": <str>,
        "status": <str>,
        "title": <str>,
        "trn": <str>,
        "type": <str>,
        "url": <str>,
        "uuid": <str>
      },
      "itemType": "PLAYLIST",
      "lastModifiedAt": <str>,
      "name": <str>,
      "parent": {
        "id": <str>,
        "name": <str>
      },
      "trn": <str>
    }
  ],
  "lastModifiedAt": <str>,
}

get_my_playlists(*, cursor: str | None = None, limit: int = 50, playlist_types: str | Collection[str] | None = None, sort_by: str | None = None, descending: bool | None = None) → dict[str, Any]

Get TIDAL catalog information for playlists in the current user’s collection.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

limitint; keyword-only; default: 50

Maximum number of playlists to return.

Valid range: 1 to 50.

cursorstr; keyword-only; optional

Cursor for fetching the next page of results.

playlist_typesstr or Collection[str]; keyword-only; optional

Playlist types to return. If not specified, all playlists are returned.

Valid values:

• "FOLDER" – Playlist folders.

• "PLAYLIST" – All playlists.

• "FAVORITE_PLAYLIST" – Favorited playlists.

• "USER_PLAYLIST" – User-created playlists.

Examples: "USER_PLAYLIST", "FOLDER,USER_PLAYLIST", ["FOLDER", "USER_PLAYLIST"].

sort_bystr; keyword-only; optional

Field to sort the playlists by.

Valid values:

• "DATE" - Date added.

• "NAME" - Playlist name.

API default: "DATE".

descendingbool; keyword-only; optional

Whether to sort in descending order.

API default: False.

Returns:

playlistsdict[str, Any]

Page of TIDAL metadata for the playlists in the current user’s collection.

Sample response

{
  "cursor": <str>,
  "items": [
    {
      "addedAt": <str>,
      "data": {
        "createdAt": <str>,
        "id": <str>,
        "itemType": "FOLDER",
        "lastModifiedAt": <str>,
        "name": <str>,
        "totalNumberOfItems": <int>,
        "trn": <str>,
      },
      "itemType": "FOLDER",
      "lastModifiedAt": <str>,
      "name": <str>,
      "parent": {
        "id": <str>,
        "name": <str>
      },
      "trn": <str>,
    },
    {
      "addedAt": <str>,
      "data": {
        "contentBehavior": <str>,
        "created": <str>,
        "creator": {
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": <str>
        },
        "curators": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>
          }
        ],
        "customImageUrl": <str>,
        "description": <str>,
        "duration": <int>,
        "image": <str>,
        "itemType": "PLAYLIST",
        "lastItemAddedAt": <str>,
        "lastUpdated": <str>,
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "promotedArtists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>
          }
        ],
        "sharingLevel": <str>,
        "source": <str>,
        "squareImage": <str>,
        "status": <str>,
        "title": <str>,
        "trn": <str>,
        "type": <str>,
        "url": <str>,
        "uuid": <str>
      },
      "itemType": "PLAYLIST",
      "lastModifiedAt": <str>,
      "name": <str>,
      "parent": {
        "id": <str>,
        "name": <str>
      },
      "trn": <str>
    }
  ],
  "lastModifiedAt": <str>
}

get_playlist(playlist_uuid: str, /, *, country_code: str | None = None, api_version: int = 2) → dict[str, Any]

Get TIDAL catalog information for a playlist.

User authentication

Conditional

User authentication

Access and manage the user’s collection.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "0ae80812-f8d6-4fc4-90ea-b2df4ecc3861".

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used. Only applicable when version is 1.

Example: "US".

api_versionint; keyword-only; default: 2

Private TIDAL API version.

Valid values:

• 1 – Legacy GET /v1/playlists/{playlist_uuid} endpoint.

• 2 – Current GET /v2/user-playlists/{playlist_uuid} endpoint.

Returns:

playlistdict[str, Any]

TIDAL metadata for the playlist.

Sample responses

Current endpoint

{
  "followInfo": {
    "followType": "PLAYLIST",
    "followed": <bool>,
    "nrOfFollowers": <int>,
    "tidalResourceName": <str>
  },
  "playlist": {
    "contentBehavior": <str>,
    "created": <str>,
    "creator": {
      "id": <int>,
      "name": <str>,
      "picture": <str>,
      "type": "USER"
    },
    "curators": [
      {
        "handle": <str>,
        "id": <int>,
        "name": <str>,
        "picture": <str>
      }
    ],
    "customImageUrl": <str>,
    "description": <str>,
    "duration": <int>,
    "image": <str>,
    "lastItemAddedAt": <str>,
    "lastUpdated": <str>,
    "numberOfTracks": <int>,
    "numberOfVideos": <int>,
    "promotedArtists": [
      {
        "contributionLinkUrl": <str>,
        "handle": <str>,
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "type": <str>,
        "userId": <int>
      }
    ],
    "sharingLevel": "PUBLIC",
    "source": <str>,
    "squareImage": <str>,
    "status": <str>,
    "title": <str>,
    "trn": <str>,
    "type": "USER",
    "url": <str>,
    "uuid": <str>
  },
  "profile": {
    "color": <list[str]>,
    "name": <str>,
    "userId": <int>
  }
}

Legacy endpoint

{
  "created": <str>,
  "creator": {
    "id": <int>
  },
  "customImageUrl": <str>,
  "description": <str>,
  "duration": <int>,
  "image": <str>,
  "lastItemAddedAt": <str>,
  "lastUpdated": <str>,
  "numberOfTracks": <int>,
  "numberOfVideos": <int>,
  "popularity": <int>,
  "promotedArtists": [
    {
      "handle": <str>,
      "id": <int>,
      "name": <str>,
      "picture": <str>,
      "type": <str>
    }
  ],
  "publicPlaylist": <bool>,
  "squareImage": <str>,
  "title": <str>,
  "type": <str>,
  "url": <str>,
  "uuid": <str>
}

get_playlist_items(playlist_uuid: str, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None) → dict[str, Any]

Get TIDAL catalog information for tracks and videos in a playlist.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

limitint; keyword-only; optional

Maximum number of items to return.

Valid range: 1 to 100.

API default: 10.

offsetint; keyword-only; optional

Index of the first item to return. Use with limit to get the next set of items.

Minimum value: 0.

API default: 0.

Returns:

itemsdict[str, Any]

Page of TIDAL metadata for the playlist’s tracks and videos.

Sample response

{
  "items": [
    {
      "cut": <Any>,
      "item": {
        "accessType": <str>,
        "adSupportedStreamReady": <bool>,
        "album": {
          "cover": <str>,
          "id": <int>,
          "releaseDate": <str>,
          "title": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "allowStreaming": <bool>,
        "artist": {
          "handle": <str>,
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": <str>
        },
        "artists": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": <str>
          }
        ],
        "audioModes": <list[str]>,
        "audioQuality": <str>,
        "bpm": <int>,
        "copyright": <str>,
        "dateAdded": <str>,
        "description": <str>,
        "djReady": <bool>,
        "duration": <int>,
        "editable": <bool>,
        "explicit": <bool>,
        "id": <int>,
        "index": <int>,
        "isrc": <str>,
        "itemUuid": <str>,
        "key": <str>,
        "keyScale": <str>,
        "mediaMetadata": {
          "tags": <list[str]>
        },
        "mixes": {
          "TRACK_MIX": <str>
        },
        "payToStream": <bool>,
        "peak": <float>,
        "popularity": <int>,
        "premiumStreamingOnly": <bool>,
        "replayGain": <float>,
        "spotlighted": <bool>,
        "stemReady": <bool>,
        "streamReady": <bool>,
        "streamStartDate": <str>,
        "title": <str>,
        "trackNumber": <int>,
        "upload": <bool>,
        "url": <str>,
        "version": <str>,
        "volumeNumber": <int>
      },
      "type": "track"
    },
    {
      "cut": <Any>,
      "item": {
        "adSupportedStreamReady": <bool>,
        "adsPrePaywallOnly": <bool>,
        "adsUrl": <str>,
        "album": {
          "cover": <str>,
          "id": <int>,
          "title": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "allowStreaming": <bool>,
        "artist": {
          "handle": <str>,
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": <str>
        },
        "artists": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": <str>
          }
        ],
        "dateAdded": <str>,
        "djReady": <bool>,
        "duration": <int>,
        "explicit": <bool>,
        "id": <int>,
        "imageId": <str>,
        "imagePath": <str>,
        "index": <int>,
        "itemUuid": <str>,
        "popularity": <int>,
        "quality": <str>,
        "releaseDate": <str>,
        "stemReady": <bool>,
        "streamReady": <bool>,
        "streamStartDate": <str>,
        "title": <str>,
        "trackNumber": <int>,
        "type": <str>,
        "vibrantColor": <str>,
        "volumeNumber": <int>
      },
      "type": "video"
    }
  ],
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>
}

get_playlist_recommended_tracks(playlist_uuid: str, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None) → dict[str, Any]

Get TIDAL catalog information for tracks recommended based on a playlist.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

limitint; keyword-only; optional

Maximum number of tracks to return.

Valid range: 1 to 100.

API default: 10.

offsetint; keyword-only; optional

Index of the first track to return. Use with limit to get the next set of tracks.

Minimum value: 0.

API default: 0.

Returns:

tracksdict[str, Any]

Page of TIDAL metadata for the recommended tracks.

Sample response

{
  "items": [
    {
      "item": {
        "accessType": <str>,
        "adSupportedStreamReady": <bool>,
        "album": {
          "cover": <str>,
          "id": <int>,
          "releaseDate": <str>,
          "title": <str>,
          "url": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "allowStreaming": <bool>,
        "artist": {
          "handle": <str>,
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": <str>
        },
        "artists": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": <str>
          }
        ],
        "audioModes": <list[str]>,
        "audioQuality": <str>,
        "copyright": <str>,
        "description": <str>,
        "djReady": <bool>,
        "doublePopularity": <float>,
        "duration": <int>,
        "editable": <bool>,
        "explicit": <bool>,
        "id": <int>,
        "isrc": <str>,
        "mediaMetadata": {
          "tags": <list[str]>
        },
        "mixes": {
          "TRACK_MIX": <str>
        },
        "payToStream": <bool>,
        "peak": <float>,
        "popularity": <int>,
        "premiumStreamingOnly": <bool>,
        "replayGain": <float>,
        "spotlighted": <bool>,
        "stemReady": <bool>,
        "streamReady": <bool>,
        "streamStartDate": <str>,
        "title": <str>,
        "trackNumber": <int>,
        "upload": <bool>,
        "url": <str>,
        "version": <str>,
        "volumeNumber": <int>
      },
      "type": "track"
    }
  ],
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>
}

get_user_created_playlists(user_id: int | str | None = None, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None) → dict[str, Any]

Get TIDAL catalog information for user-created playlists in a user’s collection.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

user_idint or str; positional-only; optional

TIDAL ID of the user. If not specified, the current user’s TIDAL ID is used.

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

limitint; keyword-only; optional

Maximum number of playlists to return.

Valid range: 1 to 100.

API default: 10.

offsetint; keyword-only; optional

Index of the first playlist to return. Use with limit to get the next batch of playlists.

Minimum value: 0.

API default: 0.

sort_bystr; keyword-only; optional

Field to sort the playlists by.

Valid values:

• "DATE" - Date added.

• "NAME" - Playlist name.

API default: "DATE".

descendingbool; keyword-only; optional

Whether to sort in descending order.

API default: False.

Returns:

playlistsdict[str, Any]

Page of TIDAL metadata for the user-created playlists in the user’s collection.

Sample response

{
  "items": [
    {
      "created": <str>,
      "playlist": {
        "created": <str>,
        "creator": {
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": <str>
        },
        "customImageUrl": <str>,
        "description": <str>,
        "duration": <int>,
        "image": <str>,
        "lastItemAddedAt": <str>,
        "lastUpdated": <str>,
        "numberOfTracks": <int>,
        "numberOfVideos":<int>,
        "popularity": <int>,
        "promotedArtists": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": <str>
          }
        ],
        "publicPlaylist": <bool>,
        "squareImage": <str>,
        "title": <str>,
        "type": <str>,
        "url": <str>,
        "uuid": <str>
      },
      "type": "USER_CREATED"
    }
  ],
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>
}

get_user_playlists(user_id: int | str | None = None, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None, sort_by: str | None = None, descending: bool | None = None) → dict[str, Any]

Get TIDAL catalog information for editorial and user-created playlists in a user’s collection.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

user_idint or str; positional-only; optional

TIDAL ID of the user. If not specified, the current user’s TIDAL ID is used.

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

limitint; keyword-only; optional

Maximum number of playlists to return.

Valid range: 1 to 100.

API default: 10.

offsetint; keyword-only; optional

Index of the first playlist to return. Use with limit to get the next batch of playlists.

Minimum value: 0.

API default: 0.

sort_bystr; keyword-only; optional

Field to sort the playlists by.

Valid values:

• "DATE" - Date added.

• "NAME" - Playlist name.

API default: "DATE".

descendingbool; keyword-only; optional

Whether to sort in descending order.

API default: False.

Returns:

playlistsdict[str, Any]

Page of TIDAL metadata for the editorial and user-created playlists in the user’s collection.

Sample response

{
  "items": [
    {
      "created": <str>,
      "playlist": {
        "created": <str>,
        "creator": {
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": <str>
        },
        "customImageUrl": <str>,
        "description": <str>,
        "duration": <int>,
        "image": <str>,
        "lastItemAddedAt": <str>,
        "lastUpdated": <str>,
        "numberOfTracks": <int>,
        "numberOfVideos":<int>,
        "popularity": <int>,
        "promotedArtists": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": <str>
          }
        ],
        "publicPlaylist": <bool>,
        "squareImage": <str>,
        "title": <str>,
        "type": <str>,
        "url": <str>,
        "uuid": <str>
      },
      "type": "USER_CREATED"
    },
    {
      "created": <str>,
      "playlist": {
        "created": <str>,
        "creator": {
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": <str>
        },
        "customImageUrl": <str>,
        "description": <str>,
        "duration": <int>,
        "image": <str>,
        "lastItemAddedAt": <str>,
        "lastUpdated": <str>,
        "numberOfTracks": <int>,
        "numberOfVideos":<int>,
        "popularity": <int>,
        "promotedArtists": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": <str>
          }
        ],
        "publicPlaylist": <bool>,
        "squareImage": <str>,
        "title": <str>,
        "type": <str>,
        "url": <str>,
        "uuid": <str>
      },
      "type": "USER_FAVORITE"
    }
  ],
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>
}

get_user_public_playlists(user_id: int | str | None = None, /, *, cursor: str | None = None, limit: int | None = None) → dict[str, Any]

Get TIDAL catalog information for public playlists in a user’s collection.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

user_idint or str; positional-only; optional

TIDAL ID of the user. If not specified, the current user’s TIDAL ID is used.

limitint; keyword-only; optional

Maximum number of playlists to return.

Valid range: 1 to 10_000.

cursorstr; keyword-only; optional

Cursor for fetching the next page of results.

Returns:

playlistsdict[str, Any]

Page of TIDAL metadata for the public playlists in the user’s collection.

Sample response

{
  "cursor": <str>,
  "items": [
    {
      "followInfo": {
        "followType": "PLAYLIST",
        "followed": <bool>,
        "nrOfFollowers": <int>,
        "tidalResourceName": <str>
      },
      "playlist": {
        "contentBehavior": <str>,
        "created": <str>,
        "creator": {
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": "USER"
        },
        "curators": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>
          }
        ],
        "customImageUrl": <str>,
        "description": <str>,
        "duration": <int>,
        "image": <str>,
        "lastItemAddedAt": <str>,
        "lastUpdated": <str>,
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "promotedArtists": [
          {
            "contributionLinkUrl": <str>,
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": <str>,
            "userId": <int>
          }
        ],
        "sharingLevel": "PUBLIC",
        "source": <str>,
        "squareImage": <str>,
        "status": <str>,
        "title": <str>,
        "trn": <str>,
        "type": "USER",
        "url": <str>,
        "uuid": <str>
      },
      "profile": {
        "color": <list[str]>,
        "name": <str>,
        "userId": <int>
      }
    }
  ]
}

move_playlists(playlist_uuids: str | Collection[str], /, folder_uuid: str | None = None) → None

Move playlists in the current user’s collection.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

playlist_uuidsstr or Collection[str]; positional-only

UUIDs or TIDAL resource names of the playlists.

Examples:

• "trn:playlist:0ae80812-f8d6-4fc4-90ea-b2df4ecc3861"

• "trn:playlist:0ae80812-f8d6-4fc4-90ea-b2df4ecc3861,24c9cc46-2fcd-4afb-bcc6-d6c42315f32e"

• ["trn:playlist:0ae80812-f8d6-4fc4-90ea-b2df4ecc3861", "24c9cc46-2fcd-4afb-bcc6-d6c42315f32e"]

folder_uuidstr

UUID of TIDAL playlist folder to move playlists to. Use "root" or leave blank to target the top-level “Playlists” folder.

remove_playlist_items(playlist_uuid: str, /, item_indices: int | str | OrderedCollection[int | str], country_code: str | None = None) → None

Remove items from a playlist.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "0ae80812-f8d6-4fc4-90ea-b2df4ecc3861".

item_indicesint, str, or OrderedCollection[int | str]

Zero-based indices of items to remove.

Examples: 1, "2", "3,4", [5, "6"].

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

reorder_playlist_items(playlist_uuid: str, /, from_item_indices: int | str | OrderedCollection[int | str], to_index: int | str, country_code: str | None = None) → None

Reorder items in a playlist.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "0ae80812-f8d6-4fc4-90ea-b2df4ecc3861".

from_item_indicesint, str, or OrderedCollection[int | str]

Zero-based indices of items to move.

Examples: 1, "2", "3,4", [5, "6"].

to_indexint or str

Zero-based index to move the items to.

Examples: 0, "0".

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

replace_playlist_item(playlist_uuid: str, /, item_index: int | str, item_id: int | str, country_code: str | None = None) → None

Replace an item in a playlist with another item.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "0ae80812-f8d6-4fc4-90ea-b2df4ecc3861".

item_indexint or str

Zero-based index of the item to be replaced.

Examples: 1, "2".

item_idint or str

TIDAL ID of the track or video to replace the item at the specified index.

Examples: 46369325, "75413016".

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

set_playlist_visibility(playlist_uuid: str, /, public: bool) → None

Set the visibility of a playlist.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

publicbool

Whether the playlist is displayed on the user’s profile.

unfollow_playlists(playlist_uuids: str | Collection[str], /, *, user_id: int | str | None = None, api_version: int = 2) → None

Remove playlists from a user’s collection.

User authentication

Required

User authentication

Access and manage the user’s collection.

Parameters:

playlist_uuidsstr or Collection[str]; positional-only; optional

Playlist UUIDs. TIDAL resource names may be provided only when version=2.

Examples:

• "trn:playlist:0ae80812-f8d6-4fc4-90ea-b2df4ecc3861"

• "trn:playlist:0ae80812-f8d6-4fc4-90ea-b2df4ecc3861,24c9cc46-2fcd-4afb-bcc6-d6c42315f32e"

• :code:[“trn:playlist:0ae80812-f8d6-4fc4-90ea-b2df4ecc3861”, “24c9cc46-2fcd-4afb-bcc6-d6c42315f32e”]

user_idint or str; keyword-only; optional

TIDAL ID of the user. If not specified, the current user’s TIDAL ID is used. Only applicable when version is 1.

api_versionint; keyword-only; default: 2

Private TIDAL API version.

Valid values:

• 1 – Legacy POST /v1/users/{user_id}/favorites/playlists endpoint.

• 2 – Current PUT /v2/my-collection/playlists/folders/add-favorites endpoint.

update_playlist_details(playlist_uuid: str, /, *, name: str | None = None, description: str | None = None) → None

Update the details of a playlist.

User authentication

Required

User authentication

Access and manage the user’s collection.

Important

Either name or description must be specified.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "0ae80812-f8d6-4fc4-90ea-b2df4ecc3861".

namestr; keyword-only; optional

New playlist name.

descriptionstr; keyword-only; optional

New playlist description.