Display tagged content

Tags are used in the Tuned Global CMS to group content such as artists, albums, playlists, radio stations, audiobooks, podcast channels, and other catalogue items.

They are typically managed by a content, editorial, or operations team in the CMS, then used by your app to build shelves, collections, category pages, discovery areas, or personalised content experiences.

This allows non-technical teams to update which content appears in the app by changing tag assignments in the CMS, without requiring a front-end release.

How tagged content works

A typical workflow looks like this:

1. A CMS user creates or selects a tag in the Tuned Global CMS.
2. They assign the tag to relevant content, such as playlists, albums, artists, or stations.
3. Your app retrieves the tag or tagged content using Tuned Global APIs.
4. Your front end displays the returned content in the relevant area of the app.
5. If the tag assignments change in the CMS, the app can display the updated content after the relevant cache refreshes.

The CMS controls which content is linked to the tag. The APIs are used to retrieve and display that tagged content in your app.

Retrieve a tag by name

If your app needs to look up a specific tag, use the ​Get by Name​ endpoint.

👉 ​Endpoint:​ ​GET​ /api/v2.4/tags

Use this when your app already knows the tag name and needs to retrieve the tag details before loading tagged content.

Example request:

👉 ​Endpoint:​ ​GET​ /api/v2.4/tags?name=workout StoreId: ​YOUR_STORE_ID

Use the API Reference for the exact query parameters required by your implementation.

Retrieve multiple tags by name

If your app needs to resolve several tags at once, use the ​Get Multiple by Name​ endpoint.

👉 ​Endpoint:​ ​GET​ /api/v2.4/tags/multiple

This can be useful when building a page that contains several tagged sections, such as:

• Workout
• New Releases
• Kids
• Local Artists
• Trending

Instead of resolving each tag individually, your app can retrieve multiple tag records and then use them to load the relevant tagged content.

Retrieve tags by tag type

Use the ​Get Tags by Tag Type​ endpoint when your app needs to display a list of tags from a specific tag category.

👉 ​Endpoint:​ ​GET​ /api/v2.4/tags/tagtype

This is useful when building browse or discovery experiences where users select from a group of tags, such as genres, moods, activities, or editorial categories.

For example, your app could retrieve a list of genre tags and display them as selectable tiles. When a user selects one of those tags, your app can retrieve the relevant content for that tag.

Retrieve artists by tag

Use the ​Get Artists by Tag​ endpoint to display artists linked to a specific tag.

👉 ​Endpoint:​ ​GET​ /api/v2.4/tags/artists

Use this when building artist discovery pages, genre-based artist collections, or campaign areas that promote specific groups of artists.

Example use cases:

• show local artists tagged with ​greenlandic
• show artists linked to a genre tag
• show artists associated with a campaign or editorial theme

Retrieve albums by tag

Use the ​Get Albums by Tag​ endpoint to display albums linked to a specific tag.

👉 ​Endpoint:​ ​GET​ /api/v2.4/tags/albums

Use this when building album shelves, genre pages, campaign collections, or editorial album recommendations.

For example, a CMS user may tag several albums with ​new releases​, ​summer​, or ​local favourites​. Your app can retrieve the albums linked to that tag and render them as a shelf or collection page.

Retrieve stations by tag

Use the ​Get Stations by Tag​ endpoint to display radio stations linked to a specific tag.

👉 ​Endpoint:​ ​GET​ /api/v2.4/tags/stations

Use this when your app needs to show grouped radio stations, such as:

• workout stations
• kids stations
• mood-based stations
• country-specific stations
• editorial station collections

When a user selects a station, your app should route them to the relevant station experience.

Retrieve playlists by tag

Use the ​Get Playlists by Tag​ endpoint to display playlists linked to a specific tag.

👉 ​Endpoint:​ ​GET​ /api/v2.4/tags/playlists

Use this when building playlist shelves or tagged playlist pages.

For example, your CMS team may tag several playlists with ​chill​, ​workout​, ​kids​, or ​new releases​. Your app can retrieve those playlists and display them without hardcoding playlist IDs in the front end.

Retrieve audiobooks or podcast channels by tag

If your service includes audiobooks or podcasts, tags can also be used to organise and surface that content.

Use the relevant browse-by-tag endpoints:

👉 ​Endpoint:​ ​GET​ /api/v2.4/tags/audiobooks

👉 ​Endpoint:​ ​GET​ /api/v2.4/tags/podcasts

Use these endpoints when building themed audiobook or podcast collections, such as wellbeing, children’s stories, education, or local content.

Retrieve content by tag groups

The API Reference also includes tag group endpoints for albums and artists.

👉 ​Endpoint:​ ​GET​ /api/v2.4/tags/groups/albums

👉 ​Endpoint:​ ​GET​ /api/v2.4/tags/groups/artists

Use tag groups when your app needs to retrieve content using a grouped tag structure, rather than a single tag.

For example, your CMS team may organise tags into broader groups such as genres, moods, regions, or campaigns. Your app can use the tag group endpoint to retrieve content associated with that grouped structure.

Display tagged content in your app

The API response should be used to render the tagged content in your app. Your front end should use the returned data to display the correct title, image, content type, and destination.

Depending on the endpoint used, the returned content may represent different item types:

Your app should not hardcode which items appear under a tag. The CMS should control the tag assignments, while the app renders the content returned by the API.

Use tagged content on a homepage

Tagged content is often used to power homepage shelves.

For example, a CMS team could create a homepage row called “Workout” and use a ​workout​ tag to control which playlists, albums, stations, or artists appear in that section.

Your app can:

1. retrieve the homepage configuration;
2. identify that a section is powered by a tag;
3. call the relevant tag endpoint for the content type;
4. render the returned items in the homepage shelf.

This makes homepage content easier to maintain because the CMS team can update the shelf by changing tag assignments rather than asking developers to update IDs in the app.

Route users from tagged content

When a user selects a tagged content item, your app should route them based on the content type returned by the API.

For example:

• if the item is a playlist, open the playlist detail page;
• if the item is a radio station, open or start the station experience;
• if the item is an album, open the album detail page;
• if the item is an artist, open the artist page;
• if the item is an audiobook, open the audiobook detail page;
• if the item is a podcast channel, open the podcast channel page.

Where additional data is required, call the relevant API endpoint for that content type after the user selects the item.

Recommended implementation pattern

1. Confirm the tag is configured in the CMS​ The tag should be created, enabled, and assigned to the relevant content by a CMS user.
2. Decide what content type to display​ Choose whether the app should display playlists, artists, albums, stations, audiobooks, podcast channels, or another supported content type.
3. Call the relevant tag endpoint​ Use the endpoint for the selected content type, such as ​GET/api/v2.4/tags/playlists, ​GET/api/v2.4/tags/albums, ​GET/api/v2.4/tags/artists, or ​GET/api/v2.4/tags/stations.
4. Render the returned content​ Display the title, image, content type, and metadata returned by the API.
5. Route users based on item type​ When a user selects an item, open the relevant detail page or playback experience.
6. Respect visibility and catalogue rules​ Your app should respect any content tier, language, country, territory, rights, access, or availability rules returned or enforced by the API.
7. Handle empty or unavailable results​ If a tag has no available content for the user, territory, or service, your app should hide the shelf, show a fallback, or display an empty state.
8. Handle updates and caching​ If tag assignments are updated in the CMS, the change may not appear instantly in the app because caching may be used for performance. If an immediate update is required, the relevant tag cache may need to be cleared or refreshed.

Related API Reference sections

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

Important notes

Tags are managed in the CMS and consumed through the APIs. Developers should avoid hardcoding tagged content if the section is intended to be managed by editorial, content, or operations teams.

The app should render tagged content based on the items returned by the API, including their order, images, content type, and destination.

If the tag has language-specific labels or images, make sure the app displays the correct localisation where available.

If a tag assignment, tag image, or tagged content collection is updated in the CMS, the change may not appear instantly in the app because caching may be used for performance.

If the app needs the update to appear immediately, clear or refresh the relevant tag cache from the CMS, then refresh the app content.