Use featured carousels

Featured carousels are configured in the Tuned Global CMS and can be used to promote content in your app, such as playlists, radio stations, albums, artists, content pages, campaigns, or custom banners.

They are typically managed by an editorial, content, or marketing team in the CMS, then retrieved by your app through Tuned Global APIs. This allows non-technical teams to update what appears in featured areas of the app without requiring a front-end release.

How featured carousels work

A typical workflow looks like this:

1. A CMS user creates or updates a featured carousel in the Tuned Global CMS.
2. They add the content or banners they want to promote.
3. They configure any required language, country, or visibility rules.
4. Your app retrieves the carousel items using Tuned Global APIs.
5. Your front end renders the carousel and routes users to the correct destination when they select an item.

The CMS is used to configure the carousel. The APIs are used to retrieve and display the carousel content in your app.

Retrieve carousel items for a page

To retrieve carousel or page items configured in the CMS, use the Get Items endpoint.

👉 Endpoint: GET /api/v2.4/pages/{name}/items

Use this endpoint when your app needs to retrieve the configured items for a specific CMS page or carousel area.

For example, your CMS team may configure a homepage carousel with: a featured playlist, a promoted radio station, a campaign banner, a new album, a seasonal collection.

Your app can request the items for that page and render them in the order returned by the API.

Example request:

👉 Endpoint: GET /api/v2.4/pages/{name}/items StoreId: YOUR_STORE_ID

Replace {name} with the page or carousel name configured for your service.

Retrieve public carousel items

Use the Get Public Items endpoint when you need to retrieve public items for a CMS page.

👉 Endpoint: GET /api/v2.4/pages/{name}/publicitems

This can be useful when the page or carousel contains content that should be available without the same user-specific context as authenticated app areas.

Example request:

👉 Endpoint: GET /api/v2.4/pages/{name}/publicitems StoreId: YOUR_STORE_ID

Use the API Reference to confirm when your implementation should use items or publicitems, based on your app’s authentication flow and content visibility rules.

Retrieve carousel items by language

If your service supports multiple languages, the CMS may be configured with language-specific carousel content.

Use the Carousel by Language endpoint to retrieve the carousel content for the relevant language.

👉 Endpoint: GET /api/v2.4/pages/carouselbylanguage

Use this when your app needs to display different carousel content depending on the user’s selected language or app locale.

For example, a service may show one carousel for English-speaking users and another for Thai-speaking users. Your app should request the appropriate language version and render the content returned by the API.

Retrieve carousel items by country

If your service supports country-specific carousel content, use the Carousel by Country endpoint.

👉 Endpoint: GET /api/v2.4/pages/carousel-by-country

Use this when carousel content should vary by country, territory, or market.

For example, your CMS team may promote different playlists, radio stations, or campaigns in Australia, Thailand, or Italy. Your app should request the correct country version and display the carousel items returned by the API.

Display and open carousel items in your app

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

Your app should not hardcode carousel content. The CMS should control what appears in the carousel, while the app renders the items returned by the API.

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

For example, if the carousel item links to a playlist, your app can use the playlist ID returned in the carousel item to retrieve the playlist details and tracks.

Recommended implementation pattern

1. Confirm the carousel is configured in the CMS The carousel, page, or featured content area should first be configured by a CMS user.
2. Choose the correct carousel endpoint Use GET /api/v2.4/pages/{name}/items for a configured CMS page or carousel area. Use the language or country-specific endpoints when your carousel should vary by locale or market.
3. Retrieve the carousel items Call the relevant endpoint and include the required headers, such as StoreId.
4. Render the carousel in your app Display the title, image, and content returned by the API. Keep the order returned by the API unless your product requirements say otherwise.
5. Route users based on item type When a user selects an item, open the correct destination, such as a playlist, radio station, album, artist page, content page, or custom banner link.
6. Respect content and visibility rules Your app should respect any access rules, territory restrictions, language settings, country settings, content tiers, or availability rules returned or enforced by the API.
7. Handle updates and caching If carousel content, artwork, or linked content is updated in the CMS, the update may not appear instantly in the app because caching may be used for performance. If an immediate update is required, the relevant 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

Featured carousels are configured in the CMS and consumed through the APIs. Developers should not hardcode featured content if the carousel is intended to be managed by the CMS.

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

If your service uses language-specific or country-specific carousel rules, make sure the app calls the correct endpoint and passes the required context.

If a carousel item points to content that is no longer available, your app should handle that gracefully, for example by hiding the item, skipping it, or showing a fallback state.