Use system playlists in your app

System playlists are playlists created and managed in the Tuned Global CMS. They are typically curated by an editorial, content, or operations team, then published so they can be retrieved and displayed in your app through Tuned Global APIs.

Use system playlists when you want to power curated music experiences such as editorial playlists, featured collections, mood-based playlists, genre pages, homepage shelves, campaign playlists, or playlists promoted to specific user tiers.

How system playlists work

A typical workflow looks like this:

1. A CMS user creates a playlist in the Tuned Global CMS.
2. They add tracks, artwork, tags, language settings, content tier rules, and other metadata.
3. The playlist is published.
4. Your app retrieves the playlist using Tuned Global APIs.
5. Your front end displays the playlist metadata, artwork, and track list to users.

The CMS is where the playlist is managed. The APIs are how your app consumes the published playlist.

Retrieve published system playlists

To retrieve a list of published playlists, use the Get Playlists endpoint.

👉 Endpoint: GET https://api-services-connect.tunedglobal.com/api/v3/collection/playlists?type=System

This endpoint can be used to return playlists that are available to your service. Depending on your API version and configuration, you may be able to filter the response using query parameters such as:

Include your StoreId in the request header so the API returns playlists for the correct service.

StoreId: YOUR_STORE_ID

Example: display CMS playlists on a homepage

For example, your CMS team may create several system playlists:

• New Releases
• Workout Hits
• Chill Evening
• Kids Favourites
• Local Artists

Once these playlists are published, your app can call the playlist endpoint with type=System to retrieve the CMS-managed playlist collection.

Example request:

👉 Endpoint: GET https://api-services-connect.tunedglobal.com/api/v3/collection/playlists?type=System&mediaType=Audio&count=10&offset=1&sort=Newest HttpHeader: StoreId:YOUR_STORE_ID

Your app can then use the response to display a playlist shelf, including the playlist title, description, artwork, and playlist ID.

Retrieve a specific playlist by ID

If your app already knows the playlist ID, for example because the playlist was selected from a homepage shelf, tag page, search result, or carousel item, use the playlist details endpoint.

Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/{id} HttpHeader: StoreId:YOUR_STORE_ID

Use this when you need to open a playlist detail page and display information for one specific playlist.

Example:

👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/123456 HttpHeader: StoreId:YOUR_STORE_ID

The response can be used to display the playlist title, description, artwork, duration, track count, and other playlist metadata available for that playlist.

Retrieve the playlist tracks

After retrieving a playlist, your app will usually need to display or play the tracks inside it.

Use the relevant playlist or collection track endpoint from the API Reference to retrieve the track list for the selected playlist. In the API mapping, playlist track retrieval is associated with:

👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/{id}/tracks HttpHeader: StoreId:YOUR_STORE_ID

Use the API Reference for the exact request parameters required to retrieve tracks for a playlist in your implementation.

Retrieve playlists by tag

If your CMS team uses tags to organise playlists, your app can retrieve playlists by tag instead of hardcoding playlist IDs.

This is useful for experiences such as:

• mood pages
• genre pages
• campaign collections
• personalised shelves
• homepage modules managed by the content team

Use the Get Playlists by Tag endpoint.

👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/tags/playlists HttpHeader: StoreId:YOUR_STORE_ID

For example, if the CMS team tags several playlists with workout, your app can request playlists linked to that tag and display them in a Workout section.

This approach gives non-technical teams more control because they can update which playlists appear in the app by changing the tag assignments in the CMS, without requiring a front-end release.

Search for playlists

If your app includes search, use the playlist search endpoint to allow users to find playlists by keyword.

👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/search/playlists HttpHeader: StoreId:YOUR_STORE_ID

Use this for user-facing search experiences where playlists should appear alongside other searchable content, or in a dedicated playlist search tab.

Display playlists through CMS content pages or carousel items

If playlists are promoted through a CMS-managed page, shelf, or carousel, retrieve the configured page or carousel items rather than manually requesting individual playlist IDs.

Relevant API areas include:

This is often the best approach for homepage and discovery experiences because the CMS controls what is featured, while the app simply renders the configured content.

Check explicit status

Before displaying a playlist in a restricted experience, such as a kids' profile or family-safe mode, you can check whether the playlist contains explicit content.

👉 Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/{id}/explicit-status HttpHeader: StoreId:YOUR_STORE_ID

Use this endpoint before showing a playlist in an environment where explicit content should be excluded.

Validate playlist availability

Before displaying or playing a playlist, you may need to confirm that it is still active and visible in the catalogue for your service.

Use catalogue validation with Playlist as the content type.

POST https://api-metadata-connect.tunedglobal.com/api/v2.4/catalogue/Playlist/validate

This is useful when playlist IDs are cached, stored in your app, or linked from a previous CMS configuration. Validation helps confirm that the playlist is still available before you show it to the user.

Recommended implementation pattern

1. Retrieve all system playlists Use GET https://api-metadata-connect.tunedglobal.com/api/v3/collection/playlists?type=System when you need a list of published system playlists.
2. Open a selected playlist Use GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/{id} when the user selects a playlist.
3. Load the track list Use GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/{id}/tracks to retrieve the songs in the playlist.
4. Use tags for flexible grouping Use GET https://api-metadata-connect.tunedglobal.com/api/v2.4/tags/playlists when playlists are grouped by CMS tags.
5. Use search when the user enters a keyword Use GET https://api-metadata-connect.tunedglobal.com/api/v2.4/search/playlists for playlist search experiences.
6. Validate before display or playback Use explicit-status and catalogue validation endpoints where required, especially for restricted, kids, or profile-based experiences.

Related API Reference sections

Developers should refer to the API Reference for endpoint-level details:

Important notes

Only published playlists should be treated as available for production app experiences.

Your app should respect the access rules, content tier, rights availability, territory restrictions, and catalogue rules configured for your service.

If a playlist, tag, artwork, or carousel placement is updated in the CMS, the change may not appear instantly in the app because caching is used for performance. If an immediate update is required, the relevant cache may need to be cleared from the CMS.

Developers should not use public APIs to create or manage CMS system playlists. System playlists are created and managed in the CMS, then retrieved and displayed through Tuned Global APIs.