Tuned Global
Docs / Kids & Family

Kids & Family

Deliver explicit-safe music with allow/block lists and profile-based content filtering

Kids & Family — Quick Start Guide

Overview

This guide covers delivering explicit-safe music experiences for kids, family profiles, and restricted-content devices such as smartwatches, children's tablets, and family-shared players. By the end you'll have configured content filtering using allow/block lists, searched with explicit content excluded, and validated your safe catalogue.

Tuned Global's content control system works at the service level — allow and block lists filter what's visible across your entire catalogue, while search-level flags let you exclude explicit content per request for profile-based filtering.

Estimated time: 10–15 minutes

Important: Allow/block list functionality must be enabled on your service by Tuned Global before you can use the catalogue control endpoints. Contact Tuned Global to activate this feature for your StoreId.

Prerequisites

  • A StoreId issued by Tuned Global with allow/block list enabled
  • OAuth2 credentials (client ID and secret)
  • A Bearer token for Services API calls
  • cURL or Postman installed

How Content Filtering Works

There are two layers of content control:

Layer Where How Best For
Allow/block lists Service level (Services API v3) Explicitly permit or block specific artists, albums, and tracks across your entire service Curating a kids-safe catalogue at the platform level
Explicit flag filtering Per request (Metadata API v2.4) Exclude explicit-flagged content from search results Profile-based filtering (e.g. kids profile vs adult profile)

For a kids & family product, you'll typically use both: block lists to remove known inappropriate content at the service level, and explicit filtering on every search/browse request from a child profile.

Step 1: Authenticate

Obtain a Bearer token for managing content controls.

Endpoint: POST https://api-authentication-connect.tunedglobal.com/oauth2/token

curl -X POST "https://api-authentication-connect.tunedglobal.com/oauth2/token" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Save the access_token for all subsequent requests.

Step 2: Block Inappropriate Content

Use block lists to remove specific artists, albums, or tracks from your service's visible catalogue. Blocked content won't appear in search results, playlists, or browse endpoints.

Block Artists

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/artists

curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/artists?type=Blocklist" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[54321, 54322, 54323]'

Block Albums

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/blocklistalbums

curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/blocklistalbums" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[111001, 111002, 111003]'

Block Individual Tracks

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/blocklisttracks

curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/blocklisttracks" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[987654, 987655]'

Step 3: Build an Allow List (Optional)

For maximum control, use an allow list instead of (or alongside) a block list. When an allow list is active, only the specified content is visible — everything else is excluded by default. This is the safest approach for a dedicated kids service.

Allow Specific Artists

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/artists

curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/artists?type=Allowlist" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[12345, 12346, 12347]'

Allow Specific Albums

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/allowlistalbums

curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/allowlistalbums" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '["00602527909103", "00602537149070"]'

Note: Album allow lists use UPC codes rather than internal IDs. You can also pass a labelId query parameter to scope the allow list to a specific label.

Allow Specific Tracks

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/allowlisttracks

curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/allowlisttracks" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[987654, 987655, 987656]'

Step 4: Search with Explicit Content Excluded

For profile-based filtering (e.g. a kids profile on a family app), exclude explicit content at the search level. This works independently of allow/block lists and can be toggled per request based on the active user profile.

Search Songs — Explicit Excluded

Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs/advanced

curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs/advanced?filter.name=Happy&filter.explicit=false&filter.count=20" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Country: AU"

Setting filter.explicit=false removes all explicit-flagged tracks from results.

Check Playlist Explicit Status

Before adding a playlist to a kids profile, verify it contains no explicit content.

Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/{playlistId}/explicit-status

curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/55001/explicit-status" \
  -H "StoreId: YOUR_STORE_ID"

Use this to flag or hide playlists that contain explicit tracks.

Step 5: Review Your Lists

Audit your allow and block lists to confirm the right content is filtered.

View Blocked Artists

curl -X GET "https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/artists?type=Blocklist&count=50&offset=0" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

View Allowed Artists

curl -X GET "https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/artists?type=Allowlist&count=50&offset=0" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

View Blocked/Allowed Albums and Tracks

GET /api/v3/catalogue/control/blocklistalbums?count=50&offset=0
GET /api/v3/catalogue/control/allowlistalbums?count=50&offset=0
GET /api/v3/catalogue/control/blocklisttracks?count=50&offset=0
GET /api/v3/catalogue/control/allowlisttracks?count=50&offset=0

Remove Items from Lists

Remove a specific artist from a block or allow list:

curl -X DELETE "https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/artists/54321?type=Blocklist" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Bulk remove albums (max 100 per request):

curl -X DELETE "https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/albums?type=Blocklist" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[111001, 111002]'

Remove tracks from allow list:

curl -X DELETE "https://api-services-connect.tunedglobal.com/api/v3/catalogue/control/allowlisttracks" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[987654, 987655]'

Step 6: Validate Your Safe Catalogue

After configuring your lists, validate that the catalogue your users will see is correct.

Check Catalogue Counts

Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/catalogue/counts

curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/catalogue/counts" \
  -H "StoreId: YOUR_STORE_ID"

Returns total song, artist, and album counts for your store — confirm these numbers align with your expected safe catalogue size.

Validate Specific Content

Check whether specific items are still active and visible in your filtered catalogue.

Endpoint: POST https://api-metadata-connect.tunedglobal.com/api/v2.4/catalogue/{type}/validate

curl -X POST "https://api-metadata-connect.tunedglobal.com/api/v2.4/catalogue/Album/validate" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Content-Type: application/json" \
  -d '[111001, 111002, 111003]'

Returns any IDs that are inactive or not visible. Supported types: Album, Mix, Playlist, Channel, Episode, Books, Chapter. Maximum 200 IDs per request.

Implementation Patterns

Dedicated Kids Service

Use a separate StoreId configured with an allow list of pre-approved content. This is the strictest model — only explicitly permitted content is available.

1. Tuned Global provisions a kids-specific StoreId
2. Curate allow lists of family-safe artists, albums, and tracks
3. All API requests use the kids StoreId — no explicit content can leak through
4. Content team maintains the allow list as new releases arrive

Family App with Profile Switching

Use a single StoreId with profile-based filtering. The adult profile gets the full catalogue; the kids profile gets filtered results.

1. Block known inappropriate content at the service level (block lists)
2. When a kids profile is active, set filter.explicit=false on all search requests
3. Check playlist explicit status before displaying in the kids profile
4. Optionally maintain a curated "Kids Picks" playlist managed via the CMS

Wearables and Restricted Devices

For smartwatches, kids' tablets, or other limited-bandwidth devices:

1. Use allow lists to restrict the catalogue to a manageable size
2. Pre-cache approved playlists for offline playback (see Background Music guide)
3. Use the image engine to serve small artwork (e.g. 80x80 for watch faces)
4. Log plays for reporting even on offline devices (batch upload when synced)

Troubleshooting

Error                         Cause                                    Solution
----------------------------  ---------------------------------------- ------------------------------------------------
403 on catalogue control      Allow/block list not enabled             Contact Tuned Global to enable for your StoreId
Blocked content still shows   Cache delay or wrong StoreId             Wait for cache refresh, verify StoreId
Allow list too restrictive    Only allow-listed content visible        Review allow list, add missing content
Explicit tracks in results    filter.explicit not set                  Set filter.explicit=false on search requests
Validation returns IDs        Content is inactive or blocked           Check block list or catalogue status

Quick Reference — Content Control Endpoints

Services API (v3) — Allow/Block Lists

Endpoint                                              Method   Description
----------------------------------------------------  ------   ----------------------------------
/api/v3/catalogue/control/artists                     POST     Add artists to allow or block list
/api/v3/catalogue/control/artists                     GET      View allow or block listed artists
/api/v3/catalogue/control/artists/{id}                DELETE   Remove artist from list
/api/v3/catalogue/control/allowlistalbums             POST     Add albums to allow list (by UPC)
/api/v3/catalogue/control/allowlistalbums             GET      View allowed albums
/api/v3/catalogue/control/blocklistalbums             POST     Add albums to block list
/api/v3/catalogue/control/blocklistalbums             GET      View blocked albums
/api/v3/catalogue/control/albums/{id}                 DELETE   Remove album from list
/api/v3/catalogue/control/albums                      DELETE   Bulk remove albums (max 100)
/api/v3/catalogue/control/allowlisttracks             POST     Add tracks to allow list
/api/v3/catalogue/control/allowlisttracks             GET      View allowed tracks
/api/v3/catalogue/control/allowlisttracks             DELETE   Remove tracks from allow list
/api/v3/catalogue/control/blocklisttracks             POST     Add tracks to block list
/api/v3/catalogue/control/blocklisttracks             GET      View blocked tracks
/api/v3/catalogue/control/tracks                      DELETE   Remove tracks from block list

Metadata API (v2.4) — Filtering & Validation

Endpoint                                              Method   Description
----------------------------------------------------  ------   ----------------------------------
/api/v2.4/search/songs/advanced                       GET      Search with filter.explicit=false
/api/v2.4/playlists/{id}/explicit-status              GET      Check playlist explicit status
/api/v2.4/catalogue/counts                            GET      Store catalogue counts
/api/v2.4/catalogue/{type}/validate                   POST     Validate content visibility

Notes

  • Allow/block list endpoints require prior activation by Tuned Global on your StoreId.
  • Services API endpoints use v3 and require Authorization: Bearer {token}.
  • Metadata API endpoints use v2.4 and require StoreId header.
  • Allow and block lists operate at the service level — they affect all users on that StoreId.
  • For profile-level filtering within a single StoreId, use filter.explicit=false on search requests.
  • Replace all example IDs and credentials with your actual values from Tuned Global.
← Previous Social & UGC Quick Start

On this page