PlaylistsAPI

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

Bases: TIDALResourceAPI

Playlists API endpoints for the TIDAL API.

Important

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

Parameters:

clientminim.api._shared.APIClient

API client instance used to make HTTP requests.

Methods

add_playlist_items	Playlists > Add to Items Relationship: Add items to a playlist.
create_playlist	Playlists > Create Playlist: Create a playlist.
delete_playlist	Playlists > Delete Playlist: Delete a playlist.
follow_playlists	User Collection Playlists > Add to Items Relationship: Add playlists to a user collection․ User Collections > Add Playlists to User's Collection: Add playlists to a user's collection.
get_playlist_collection	User Collection Playlists > Get User Playlist Collection: Get TIDAL catalog information for a user playlist collection.
get_playlist_cover_art	Playlists > Get Cover Art Relationship: Get TIDAL catalog information for the cover art of a playlist.
get_playlist_items	Playlists > Get Items Relationship: Get TIDAL catalog information for items in a playlist.
get_playlist_owner_profiles	Playlists > Get Owner Profiles Relationship: Get TIDAL catalog information for the profiles of a playlist resource's owners.
get_playlist_owners	Playlists > Get Owners Relationship: Get TIDAL profile information for the owner of a playlist resource.
get_playlists	Playlists > Get Single Playlist: Get TIDAL catalog information for a playlist․ Playlists > Get Multiple Playlists: Get TIDAL catalog information for multiple playlists.
get_user_followed_playlists	User Collection Playlists > Get Items Relationship: Get TIDAL catalog information for playlists in a user collection․ User Collections > Get Playlists Relationship: Get TIDAL catalog information for playlists in a user's collection.
remove_playlist_items	Playlists > Delete from Items Relationship: Remove items from a playlist.
reorder_playlist_items	Playlists > Update Items Relationship: Reorder items in a playlist.
search_playlists	Search Results > Get Playlists Relationship: Search for playlists in the TIDAL catalog.
unfollow_playlists	User Collection Playlists > Delete from Items Relationship: Remove playlists from a user collection․ User Collections > Remove Playlists from User's Collection: Remove playlists from a user's collection.
update_playlist_details	Playlists > Update Playlist: Update the details of a playlist.

add_playlist_items(playlist_uuid: str, /, items: tuple[int | str, str] | dict[str, int | str] | Collection[tuple[int | str, str] | dict[str, int | str]], *, country_code: str | None = None, insert_before: str | None = None) → None

Playlists > Add to Items Relationship: Add items to a playlist.

Authorization scope

Required

playlists.write scope

Write to a user’s playlists.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "550e8400-e29b-41d4-a716-446655440000".

itemstuple[int | str, str], dict[str, int | str], or Collection[tuple[int | str, str] | dict[str, int | str]]

TIDAL IDs and types of the items to be added.

Examples:

• (458584456, "tracks")

• ("29597422", "videos")

• {"id": "35633900", "types": "tracks"}

• [
      (458584456, "tracks"),
      ("29597422", "videos"),
      {"id": "35633900", "types": "tracks"},
  ]
  

country_codestr; keyword-only; optional

ISO 3166-1 alpha-2 country code.

Example: "US".

insert_beforestr; keyword-only; optional

UUID of the item in the playlist before which to insert the items. If not specified, the items are appended to the end of the playlist.

Example: "3794bdb3-1529-48d7-8a99-ef2cb0cf22c3".

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

Playlists > Create Playlist: Create a playlist.

Authorization scope

Required

playlists.write scope

Write to a user’s playlists.

Parameters:

namestr

Playlist name.

country_codestr; optional

ISO 3166-1 alpha-2 country code.

descriptionstr; keyword-only; optional

Playlist description.

publicbool; keyword-only; optional

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

API default: False.

Returns:

playlistdict[str, Any]

TIDAL metadata for the newly created playlist.

Sample response

{
  "data": {
    "attributes": {
      "accessType": <str>,
      "bounded": <bool>,
      "createdAt": <str>,
      "externalLinks": [
        {
          "href": <str>,
          "meta": {
            "type": "TIDAL_SHARING"
          }
        }
      ],
      "lastModifiedAt": <str>,
      "name": <str>,
      "playlistType": "USER"
    },
    "id": <str>,
    "relationships": {
      "coverArt": {
        "links": {
          "self": <str>
        }
      },
      "items": {
        "links": {
          "self": <str>
        }
      },
      "owners": {
        "links": {
          "self": <str>
        }
      }
    },
    "type": "playlists"
  },
  "links": {
    "self": <str>
  }
}

delete_playlist(playlist_uuid: str, /) → None

Playlists > Delete Playlist: Delete a playlist.

Authorization scope

Required

playlists.write scope

Write to a user’s playlists.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "550e8400-e29b-41d4-a716-446655440000".

follow_playlists(playlist_uuids: str | dict[str, str] | Collection[str | dict[str, str]], /, *, collection_id: str | None = None, user_id: int | str | None = None) → None

User Collection Playlists > Add to Items Relationship: Add playlists to a user collection․ User Collections > Add Playlists to User’s Collection: Add playlists to a user’s collection.

Authorization scope

Required

collection.write scope

Write access to a user’s collection.

Important

At most one of collection_id or user_id must be provided. If user_id is provided, the legacy POST /userCollections/{user_id}/relationships /playlists endpoint is used.

Parameters:

playlist_uuidsstr, dict[str, str], or Collection[str | dict[str, str]]; positional-only

UUIDs and/or resource identifiers of the playlists.

Examples:

• "f0d6f5c4-081f-4348-9b65-ae677d92767b"

• {
      "id": "1e4c73df-b805-47cd-9e44-9a8721c5cb45",
      "types": "playlists"
  }
  

• [
      "f0d6f5c4-081f-4348-9b65-ae677d92767b",
      {
          "id": "1e4c73df-b805-47cd-9e44-9a8721c5cb45",
          "types": "playlists"
      }
  ]
  

collection_idstr; keyword-only; optional

TIDAL ID of the user collection. If authenticated, "me" can be used in lieu of a TIDAL ID for the current user’s collection. If not specified, "me" is used.

user_idint or str; keyword-only; optional

TIDAL ID of the user.

get_playlist_collection(collection_id: str | None = None, /, *, country_code: str | None = None, locale: str | None = None, expand: str | Collection[str] | None = None) → dict[str, Any]

User Collection Playlists > Get User Playlist Collection: Get TIDAL catalog information for a user playlist collection.

Authorization scope

Required

collection.read scope

Read access to a user’s collection.

Parameters:

collection_idstr; positional-only; optional

TIDAL ID of the user collection. If authenticated, "me" can be used in lieu of a TIDAL ID for the current user’s collection. If not specified, "me" is used.

country_codestr; keyword-only; optional

ISO 3166-1 alpha-2 country code.

Example: "US".

localestr; keyword-only; optional

IETF BCP 47 language tag.

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

Related resources to include metadata for in the response.

Valid values: "items", "owners".

Examples: "items", ["items", "owners"].

Returns:

collectiondict[str, Any]

TIDAL metadata for the user playlist collection.

Sample response

{
  "data": {
    "attributes": {},
    "id": <str>,
    "relationships": {
      "items": {
        "data": [
          {
            "id": <str>,
            "meta": {
              "addedAt": <str>
            },
            "type": "playlists"
          }
        ],
        "links": {
          "self": <str>
        }
      },
      "owners": {
        "data": [
          {
            "id": <str>,
            "type": "users"
          }
        ],
        "links": {
          "self": <str>
        }
      }
    },
    "type": "userCollectionPlaylists"
  },
  "included": [
    {
      "attributes": {
        "accessType": <str>,
        "bounded": <bool>,
        "createdAt": <str>,
        "description": <str>,
        "duration": "PT3H16M5S",
        "externalLinks": [
          {
            "href": <str>,
            "meta": {
              "type": <str>
            }
          }
        ],
        "lastModifiedAt": <str>,
        "name": <str>,
        "numberOfFollowers": <int>,
        "numberOfItems": <int>,
        "playlistType": <str>
      },
      "id": <str>,
      "relationships": {
        "coverArt": {
          "links": {
            "self": <str>
          }
        },
        "items": {
          "links": {
            "self": <str>
          }
        },
        "ownerProfiles": {
          "links": {
            "self": <str>
          }
        },
        "owners": {
          "links": {
            "self": <str>
          }
        }
      },
      "type": "playlists"
    }
  ],
  "links": {
    "self": <str>
  }
}

get_playlist_cover_art(playlist_uuid: str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None) → dict[str, Any]

Playlists > Get Cover Art Relationship: Get TIDAL catalog information for the cover art of 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.

Example: "US".

include_metadatabool; keyword-only; default: False

Whether to include metadata for the playlist cover art.

cursorstr; keyword-only; optional

Cursor for fetching the next page of results.

Example: "3nI1Esi".

Returns:

cover_artdict[str, Any]

Page of TIDAL metadata for the playlist cover art.

Sample response

{
  "data": [
    {
      "id": <str>,
      "type": "artworks"
    }
  ],
  "included": [
    {
      "attributes": {
        "files": [
          {
            "href": <str>,
            "meta": {
              "height": <int>,
              "width": <int>
            }
          }
        ],
        "mediaType": "IMAGE"
      },
      "id": <str>,
      "relationships": {
        "owners": {
          "links": {
            "self": <str>
          }
        }
      },
      "type": "artworks"
    }
  ],
  "links": {
    "meta": {
      "nextCursor": <str>
    },
    "next": <str>,
    "self": <str>
  }
}

get_playlist_items(playlist_uuid: str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None) → dict[str, Any]

Playlists > Get Items Relationship: Get TIDAL catalog information for items 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.

Example: "US".

include_metadatabool; keyword-only; default: False

Whether to include metadata for the playlist items.

cursorstr; keyword-only; optional

Cursor for fetching the next page of results.

Example: "3nI1Esi".

Returns:

itemsdict[str, Any]

Page of TIDAL metadata for the playlist items.

Sample response

{
  "data": [
    {
      "id": <str>,
      "meta": {
        "addedAt": <int>,
        "itemId": <int>
      },
      "type": "tracks"
    },
    {
      "id": <str>,
      "meta": {
        "addedAt": <int>,
        "itemId": <int>
      },
      "type": "videos"
    }
  ],
  "included": [
    {
      "attributes": {
        "accessType": <str>,
        "availability": <list[str]>,
        "bpm": <float>,
        "copyright": {
          "text": <str>
        },
        "duration": <str>,
        "explicit": <bool>,
        "externalLinks": [
          {
            "href": <str>,
            "meta": {
              "type": <str>
            }
          }
        ],
        "isrc": <str>,
        "key": <str>,
        "keyScale": <str>,
        "mediaTags": <list[str]>,
        "popularity": <float>,
        "spotlighted": <bool>,
        "title": <str>,
        "toneTags": <list[str]>,
        "version": <str>
      },
      "id": <str>,
      "relationships": {
        "albums": {
          "links": {
            "self": <str>
          }
        },
        "artists": {
          "links": {
            "self": <str>
          }
        },
        "genres": {
          "links": {
            "self": <str>
          }
        },
        "lyrics": {
          "links": {
            "self": <str>
          }
        },
        "owners": {
          "links": {
            "self": <str>
          }
        },
        "providers": {
          "links": {
            "self": <str>
          }
        },
        "radio": {
          "links": {
            "self": <str>
          }
        },
        "shares": {
          "links": {
            "self": <str>
          }
        },
        "similarTracks": {
          "links": {
            "self": <str>
          }
        },
        "sourceFile": {
          "links": {
            "self": <str>
          }
        },
        "trackStatistics": {
          "links": {
            "self": <str>
          }
        }
      },
      "type": "tracks"
    },
    {
      "attributes": {
        "availability": <list[str]>,
        "copyright": {
          "text": <str>
        },
        "duration": <str>,
        "explicit": <bool>,
        "externalLinks": [
          {
            "href": <str>,
            "meta": {
              "type": <str>
            }
          }
        ],
        "isrc": <str>,
        "popularity": <float>,
        "releaseDate": <str>,
        "title": <str>
      },
      "id": <str>,
      "relationships": {
        "albums": {
          "links": {
            "self": <str>
          }
        },
        "artists": {
          "links": {
            "self": <str>
          }
        },
        "providers": {
          "links": {
            "self": <str>
          }
        },
        "thumbnailArt": {
          "links": {
            "self": <str>
          }
        }
      },
      "type": "videos"
    }
  ],
  "links": {
    "meta": {
      "nextCursor": <str>
    },
    "next": <str>,
    "self": <str>
  }
}

get_playlist_owner_profiles(playlist_uuid: str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None) → dict[str, Any]

Playlists > Get Owner Profiles Relationship: Get TIDAL catalog information for the profiles of a playlist resource’s owners.

User authentication

Optional

User authentication

Access information for a resource’s owners.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "550e8400-e29b-41d4-a716-446655440000".

country_codestr; optional

ISO 3166-1 alpha-2 country code.

Example: "US".

include_metadatabool; keyword-only; default: False

Whether to include metadata for the playlist’s owners’ profiles.

cursorstr; keyword-only; optional

Cursor for fetching the next page of results.

Example: "3nI1Esi".

Returns:

owner_profilesdict[str, Any]

Page of TIDAL metadata for the playlist’s owners’ profiles.

Sample response

{
  "data": [],
  "included": [],
  "links": {
    "meta": {
      "nextCursor": <str>
    },
    "next": <str>,
    "self": <str>
  }
}

get_playlist_owners(playlist_uuid: str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None) → dict[str, Any]

Playlists > Get Owners Relationship: Get TIDAL profile information for the owner of a playlist resource.

User authentication

Optional

User authentication

Access information for a resource’s owners.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "550e8400-e29b-41d4-a716-446655440000".

country_codestr; optional

ISO 3166-1 alpha-2 country code.

Example: "US".

include_metadatabool; keyword-only; default: False

Whether to include metadata for the owners.

cursorstr; keyword-only; optional

Cursor for fetching the next page of results.

Example: "3nI1Esi".

Returns:

ownersdict[str, Any]

Page of TIDAL profile information for the playlist resource’s owners.

Sample response

{
  "data": [],
  "included": [],
  "links": {
    "meta": {
      "nextCursor": <str>
    },
    "next": <str>,
    "self": <str>
  }
}

get_playlists(playlist_uuids: str | Collection[str] | None = None, /, *, owner_ids: int | str | Collection[int | str] | None = None, country_code: str | None = None, expand: str | Collection[str] | None = None, cursor: str | None = None, sort_by: str | None = None, descending: bool | None = None) → dict[str, Any]

Playlists > Get Single Playlist: Get TIDAL catalog information for a playlist․ Playlists > Get Multiple Playlists: Get TIDAL catalog information for multiple playlists.

User authentication and authorization scope

Conditional

playlists.read scope

Read a user’s playlists.

Optional

User authentication

Access information for a resource’s owners.

Important

Exactly one of playlist_uuids or owner_ids must be provided. When owner_ids is specified, the request will always be sent to the endpoint for multiple playlists.

Parameters:

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

UUIDs of the TIDAL playlists.

Examples: "36ea71a8-445e-41a4-82ab-6628c581535d", ["36ea71a8-445e-41a4-82ab-6628c581535d", "b0d95b5e-7c4f-4dae-b042-b8c6228c2ba4"].

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

TIDAL IDs of the playlist resources’ owners. If authenticated, "me" can be used in lieu of a TIDAL ID for the current user.

Examples: "me", 123456, "654321", [123456, "654321"].

country_codestr; keyword-only; optional

ISO 3166-1 alpha-2 country code.

Example: "US".

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

Related resources to include metadata for in the response.

Valid values: "collaboratorProfiles", "collaborators", "coverArt", "items", "ownerProfiles", "owners".

Examples: "coverArt", ["items", "owners"].

cursorstr; keyword-only; optional

Cursor for fetching the next page of results when requesting multiple playlists.

Example: "3nI1Esi".

sort_bystr; keyword-only; optional

Field to sort the playlists by.

Valid values: "createdAt", "lastModifiedAt, "name".

descendingbool; keyword-only; optional

Whether to sort in descending order.

API default: False.

Returns:

playlistsdict[str, Any]

Page of TIDAL metadata for the playlists.

Sample responses

Single playlist

{
  "data": {
    "attributes": {
      "accessType": <str>,
      "bounded": <bool>,
      "createdAt": <str>,
      "description": <str>,
      "duration": <str>,
      "externalLinks": [
        {
          "href": <str>,
          "meta": {
            "type": <str>
          }
        }
      ],
      "lastModifiedAt": <str>,
      "name": <str>,
      "numberOfItems": <int>,
      "playlistType": <str>
    },
    "id": <str>,
    "relationships": {
      "coverArt": {
        "data": [
          {
            "id": <str>,
            "type": "artworks"
          }
        ],
        "links": {
          "self": <str>
        }
      },
      "items": {
        "data": [
          {
            "id": <str>,
            "meta": {
              "addedAt": <str>,
              "itemId": <str>
            },
            "type": "tracks"
          },
          {
            "id": <str>,
            "meta": {
              "addedAt": <str>,
              "itemId": <str>
            },
            "type": "videos"
          }
        ],
        "links": {
          "self": <str>
        }
      },
      "ownerProfiles": {
        "data": [],
        "links": {
          "self": <str>
        }
      },
      "owners": {
        "data": [],
        "links": {
          "self": <str>
        }
      }
    },
    "type": "playlists"
  },
  "included": [
    {
      "attributes": {
        "files": [
          {
            "href": <str>,
            "meta": {
              "height": <int>,
              "width": <int>
            }
          }
        ],
        "mediaType": "IMAGE"
      },
      "id": <str>,
      "relationships": {
        "owners": {
          "links": {
            "self": <str>
          }
        }
      },
      "type": "artworks"
    },
    {
      "attributes": {
        "accessType": <str>,
        "availability": <list[str]>,
        "bpm": <float>,
        "copyright": {
          "text": <str>
        },
        "duration": <str>,
        "explicit": <bool>,
        "externalLinks": [
          {
            "href": <str>,
            "meta": {
              "type": <str>
            }
          }
        ],
        "isrc": <str>,
        "key": <str>,
        "keyScale": <str>,
        "mediaTags": <list[str]>,
        "popularity": <float>,
        "spotlighted": <bool>,
        "title": <str>,
        "toneTags": <list[str]>,
        "version": <str>
      },
      "id": <str>,
      "relationships": {
        "albums": {
          "links": {
            "self": <str>
          }
        },
        "artists": {
          "links": {
            "self": <str>
          }
        },
        "genres": {
          "links": {
            "self": <str>
          }
        },
        "lyrics": {
          "links": {
            "self": <str>
          }
        },
        "owners": {
          "links": {
            "self": <str>
          }
        },
        "providers": {
          "links": {
            "self": <str>
          }
        },
        "radio": {
          "links": {
            "self": <str>
          }
        },
        "shares": {
          "links": {
            "self": <str>
          }
        },
        "similarTracks": {
          "links": {
            "self": <str>
          }
        },
        "sourceFile": {
          "links": {
            "self": <str>
          }
        },
        "trackStatistics": {
          "links": {
            "self": <str>
          }
        }
      },
      "type": "tracks"
    },
    {
      "attributes": {
        "availability": <list[str]>,
        "copyright": {
          "text": <str>
        },
        "duration": <str>,
        "explicit": <bool>,
        "externalLinks": [
          {
            "href": <str>,
            "meta": {
              "type": <str>
            }
          }
        ],
        "isrc": <str>,
        "popularity": <float>,
        "releaseDate": <str>,
        "title": <str>
      },
      "id": <str>,
      "relationships": {
        "albums": {
          "links": {
            "self": <str>
          }
        },
        "artists": {
          "links": {
            "self": <str>
          }
        },
        "providers": {
          "links": {
            "self": <str>
          }
        },
        "thumbnailArt": {
          "links": {
            "self": <str>
          }
        }
      },
      "type": "videos"
    }
  ],
  "links": {
    "self": <str>
  }
}

Multiple playlists

{
  "data": [
    {
      "attributes": {
        "accessType": <str>,
        "bounded": <bool>,
        "createdAt": <str>,
        "description": <str>,
        "duration": <str>,
        "externalLinks": [
          {
            "href": <str>,
            "meta": {
              "type": <str>
            }
          }
        ],
        "lastModifiedAt": <str>,
        "name": <str>,
        "numberOfItems": <int>,
        "playlistType": <str>
      },
      "id": <str>,
      "relationships": {
        "coverArt": {
          "data": [
            {
              "id": <str>,
              "type": "artworks"
            }
          ],
          "links": {
            "self": <str>
          }
        },
        "items": {
          "data": [
            {
              "id": <str>,
              "meta": {
                "addedAt": <str>,
                "itemId": <str>
              },
              "type": "tracks"
            },
            {
              "id": <str>,
              "meta": {
                "addedAt": <str>,
                "itemId": <str>
              },
              "type": "videos"
            }
          ],
          "links": {
            "self": <str>
          }
        },
        "ownerProfiles": {
          "data": [],
          "links": {
            "self": <str>
          }
        }
        "owners": {
          "data": [],
          "links": {
            "self": <str>
          }
        }
      },
      "type": "playlists"
    }
  ],
  "included": [
    {
      "attributes": {
        "files": [
          {
            "href": <str>,
            "meta": {
              "height": <int>,
              "width": <int>
            }
          }
        ],
        "mediaType": "IMAGE"
      },
      "id": <str>,
      "relationships": {
        "owners": {
          "links": {
            "self": <str>
          }
        }
      },
      "type": "artworks"
    },
    {
      "attributes": {
        "accessType": <str>,
        "availability": <list[str]>,
        "bpm": <float>,
        "copyright": {
          "text": <str>
        },
        "duration": <str>,
        "explicit": <bool>,
        "externalLinks": [
          {
            "href": <str>,
            "meta": {
              "type": <str>
            }
          }
        ],
        "isrc": <str>,
        "key": <str>,
        "keyScale": <str>,
        "mediaTags": <list[str]>,
        "popularity": <float>,
        "spotlighted": <bool>,
        "title": <str>,
        "toneTags": <list[str]>,
        "version": <str>
      },
      "id": <str>,
      "relationships": {
        "albums": {
          "links": {
            "self": <str>
          }
        },
        "artists": {
          "links": {
            "self": <str>
          }
        },
        "genres": {
          "links": {
            "self": <str>
          }
        },
        "lyrics": {
          "links": {
            "self": <str>
          }
        },
        "owners": {
          "links": {
            "self": <str>
          }
        },
        "providers": {
          "links": {
            "self": <str>
          }
        },
        "radio": {
          "links": {
            "self": <str>
          }
        },
        "shares": {
          "links": {
            "self": <str>
          }
        },
        "similarTracks": {
          "links": {
            "self": <str>
          }
        },
        "sourceFile": {
          "links": {
            "self": <str>
          }
        },
        "trackStatistics": {
          "links": {
            "self": <str>
          }
        }
      },
      "type": "tracks"
    },
    {
      "attributes": {
        "availability": <list[str]>,
        "copyright": {
          "text": <str>
        },
        "duration": <str>,
        "explicit": <bool>,
        "externalLinks": [
          {
            "href": <str>,
            "meta": {
              "type": <str>
            }
          }
        ],
        "isrc": <str>,
        "popularity": <float>,
        "releaseDate": <str>,
        "title": <str>
      },
      "id": <str>,
      "relationships": {
        "albums": {
          "links": {
            "self": <str>
          }
        },
        "artists": {
          "links": {
            "self": <str>
          }
        },
        "providers": {
          "links": {
            "self": <str>
          }
        },
        "thumbnailArt": {
          "links": {
            "self": <str>
          }
        }
      },
      "type": "videos"
    }
  ],
  "links": {
    "self": <str>
  }
}

get_user_followed_playlists(*, collection_id: str | None = None, user_id: int | str | None = None, include_folders: bool = False, include_metadata: bool = False, cursor: str | None = None, sort_by: str | None = None, descending: bool | None = None) → dict[str, Any]

User Collection Playlists > Get Items Relationship: Get TIDAL catalog information for playlists in a user collection․ User Collections > Get Playlists Relationship: Get TIDAL catalog information for playlists in a user’s collection.

Authorization scope

Required

collection.read scope

Read access to a user’s collection.

Important

At most one of collection_id or user_id must be provided. If user_id is provided, the legacy GET /userCollections/{user_id}/relationships /playlists endpoint is used.

Parameters:

collection_idstr; keyword-only; optional

TIDAL ID of the user collection. If authenticated, "me" can be used in lieu of a TIDAL ID for the current user’s collection. If not specified, "me" is used.

user_idint or str; keyword-only; optional

TIDAL ID of the user.

include_foldersbool; keyword-only; default: False

Whether to include metadata for playlist folders in the user’s collection.

include_metadatabool; keyword-only; default: False

Whether to include metadata for the playlists in the user’s collection.

cursorstr; keyword-only; optional

Cursor for fetching the next page of results.

Example: "3nI1Esi".

sort_bystr; keyword-only; optional

Field to sort the playlists by.

Valid values: "addedAt", "lastUpdatedAt", "name".

descendingbool; keyword-only; optional

Whether to sort in descending order.

API default: False.

Returns:

playlistsdict[str, Any]

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

Sample response

{
  "data": [
    {
      "id": <str>,
      "meta": {
        "addedAt": <str>
      },
      "type": "playlists"
    },
    {
      "id": <str>,
      "meta": {
        "addedAt": <str>
      },
      "type": "userCollectionFolders"
    }
  ],
  "included": [
    {
      "attributes": {
        "accessType": <str>,
        "bounded": <bool>,
        "createdAt": <str>,
        "description": <str>,
        "duration": <str>,
        "externalLinks": [
          {
            "href": <str>,
            "meta": {
              "type": <str>
            }
          }
        ],
        "lastModifiedAt": <str>,
        "name": <str>,
        "numberOfItems": <int>,
        "playlistType": "USER"
      },
      "id": <str>,
      "relationships": {
        "coverArt": {
          "links": {
            "self": <str>
          }
        },
        "items": {
          "links": {
            "self": <str>
          }
        },
        "owners": {
          "links": {
            "self": <str>
          }
        }
      },
      "type": "playlists"
    }
  ],
  "links": {
    "meta": {
      "nextCursor": <str>
    },
    "next": <str>,
    "self": <str>
  }
}

remove_playlist_items(playlist_uuid: str, /, items: tuple[int | str, str, str] | dict[str, Any] | Collection[tuple[int | str, str, str] | dict[str, Any]]) → None

Playlists > Delete from Items Relationship: Remove items from a playlist.

Authorization scope

Required

playlists.write scope

Write to a user’s playlists.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "550e8400-e29b-41d4-a716-446655440000".

itemstuple[int | str, str, str], dict[str, Any], or Collection[tuple[int | str, str, str] | dict[str, Any]]

TIDAL IDs, playlist item UUIDs, and types of the items to be removed.

Examples:

• (458584456, "f0d6f5c4-081f-4348-9b65-ae677d92767b", "tracks")

• ("29597422", "1e4c73df-b805-47cd-9e44-9a8721c5cb45", "videos")

• {
      "id": "35633900",
      "meta": {
          "itemId": "fdd074f0-90c7-4cfb-bb6c-10060e1a3a58"
      },
      "types": "tracks"
  }
  

• [
      (
          458584456,
          "f0d6f5c4-081f-4348-9b65-ae677d92767b",
          "tracks",
      ),
      (
          "29597422",
          "1e4c73df-b805-47cd-9e44-9a8721c5cb45",
          "videos",
      ),
      {
          "id": "35633900",
          "meta": {
              "itemId": "fdd074f0-90c7-4cfb-bb6c-10060e1a3a58"
          },
          "types": "tracks",
      },
  ]
  

See also

get_playlist_items() – Get playlist item UUIDs.

reorder_playlist_items(playlist_uuid: str, /, items: tuple[int | str, str, str] | dict[str, Any] | Collection[tuple[int | str, str, str] | dict[str, Any]], insert_before: str) → None

Playlists > Update Items Relationship: Reorder items in a playlist.

Authorization scope

Required

playlists.write scope

Write to a user’s playlists.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "550e8400-e29b-41d4-a716-446655440000".

itemstuple[int | str, str, str], dict[str, Any], or Collection[tuple[int | str, str, str] | dict[str, Any]]

TIDAL IDs, playlist item UUIDs, and types of the items to be reordered.

Examples:

• (458584456, "f0d6f5c4-081f-4348-9b65-ae677d92767b", "tracks")

• ("29597422", "1e4c73df-b805-47cd-9e44-9a8721c5cb45", "videos")

• {
      "id": "35633900",
      "meta": {
          "itemId": "fdd074f0-90c7-4cfb-bb6c-10060e1a3a58"
      },
      "types": "tracks"
  }
  

• [
      (
          458584456,
          "f0d6f5c4-081f-4348-9b65-ae677d92767b",
          "tracks",
      ),
      (
          "29597422",
          "1e4c73df-b805-47cd-9e44-9a8721c5cb45",
          "videos",
      ),
      {
          "id": "35633900",
          "meta": {
              "itemId": "fdd074f0-90c7-4cfb-bb6c-10060e1a3a58"
          },
          "types": "tracks",
      },
  ]
  

See also

get_playlist_items() – Get playlist item UUIDs.

insert_beforestr

UUID of the item in the playlist before which to insert the items.

Example: "3794bdb3-1529-48d7-8a99-ef2cb0cf22c3".

search_playlists(query: str, /, country_code: str | None = None, *, include_explicit: bool | None = None, include_metadata: bool = False, cursor: str | None = None) → dict[str, Any]

Search Results > Get Playlists Relationship: Search for playlists in the TIDAL catalog.

Authorization scope

Optional

search.read scope

Read personalized search results.

Parameters:

querystr; positional-only

Search query.

country_codestr; optional

ISO 3166-1 alpha-2 country code.

Example: "US".

include_explicitbool; keyword-only; optional

Whether to include items with explicit language.

API default: True.

include_metadatabool; keyword-only; default: False

Whether to include metadata for the matching playlists.

cursorstr; keyword-only; optional

Cursor for fetching the next page of results.

Example: "3nI1Esi".

Returns:

playlistsdict[str, Any]

Page of TIDAL metadata for the matching playlists.

Sample response

{
  "data": [
      {
        "id": <str>,
        "type": "playlists"
      }
    ],
  },
  "included": [
    {
      "attributes": {
        "accessType": <str>,
        "bounded": true,
        "createdAt": <str>,
        "description": <str>,
        "duration": <str>,
        "externalLinks": [
          {
            "href": <str>,
            "meta": {
              "type": <str>
            }
          }
        ],
        "lastModifiedAt": <str>,
        "name": <str>,
        "numberOfItems": <int>,
        "playlistType": <str>
      },
      "id": <str>,
      "relationships": {
        "coverArt": {
          "links": {
            "self": <str>
          }
        },
        "items": {
          "links": {
            "self": <str>
          }
        },
        "owners": {
          "links": {
            "self": <str>
          }
        }
      },
      "type": "playlists"
    }
  ],
  "links": {
    "meta": {
      "nextCursor": <str>
    },
    "next": <str>,
    "self": <str>
  }
}

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

User Collection Playlists > Delete from Items Relationship: Remove playlists from a user collection․ User Collections > Remove Playlists from User’s Collection: Remove playlists from a user’s collection.

Authorization scope

Required

collection.write scope

Write access to a user’s collection.

Important

At most one of collection_id or user_id must be provided. If user_id is provided, the legacy DELETE /userCollections/{user_id}/relationships /playlists endpoint is used.

Parameters:

playlist_uuidsstr, dict[str, str], or Collection[str | dict[str, str]]; positional-only

UUIDs and/or resource identifiers of the playlists.

Examples:

• "f0d6f5c4-081f-4348-9b65-ae677d92767b"

• {
      "id": "1e4c73df-b805-47cd-9e44-9a8721c5cb45",
      "types": "playlists"
  }
  

• [
      "f0d6f5c4-081f-4348-9b65-ae677d92767b",
      {
          "id": "1e4c73df-b805-47cd-9e44-9a8721c5cb45",
          "types": "playlists"
      }
  ]
  

collection_idstr; keyword-only; optional

TIDAL ID of the user collection. If authenticated, "me" can be used in lieu of a TIDAL ID for the current user’s collection. If not specified, "me" is used.

user_idint or str; keyword-only; optional

TIDAL ID of the user.

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

Playlists > Update Playlist: Update the details of a playlist.

Authorization scope

Required

playlists.write scope

Write to a user’s playlists.

Important

At least one of name, description, or public must be specified.

Parameters:

playlist_uuidstr; positional-only

UUID of the TIDAL playlist.

Example: "550e8400-e29b-41d4-a716-446655440000".

country_codestr; optional

ISO 3166-1 alpha-2 country code.

namestr; keyword-only; optional

Playlist name.

descriptionstr; keyword-only; optional

Playlist description.

publicbool; keyword-only; optional

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

API default: False.