Tuned Global
Docs / Social & UGC Quick Start

Social & UGC Quick Start

Get started with playlists, collections, and social features in 10 minutes

Social & UGC — Quick Start Guide

Overview

This quick start walks through the core social music features: saving tracks, creating a shareable playlist, following artists, and discovering community content. By the end you'll have a working social experience integrated with Tuned Global's APIs.

Estimated time: 10 minutes

For the full API reference covering all collection types, playlist CRUD, UGC video, and optional features (Social Radio, AutomixIQ, Unified Listening), see the comprehensive Social & UGC guide.

Prerequisites

  • A StoreId issued by Tuned Global
  • OAuth2 credentials (client ID and secret)
  • A test user account
  • cURL or Postman installed

Step 1: Authenticate

Obtain a Bearer token for the user session.

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=password&username=TEST_USER&password=TEST_PASSWORD"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 86400
}

Save the access_token for all subsequent requests.

Step 2: Save Tracks to Collection

Let users build a personal library by saving tracks they like.

Endpoint: PUT https://api-services-connect.tunedglobal.com/api/v3/collection/tracks/{trackId}

curl -X PUT "https://api-services-connect.tunedglobal.com/api/v3/collection/tracks/987654" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

To add several tracks at once:

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/collection/tracks

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

Retrieve the user's saved tracks:

Endpoint: GET https://api-services-connect.tunedglobal.com/api/v3/collection/tracks

curl -X GET "https://api-services-connect.tunedglobal.com/api/v3/collection/tracks?offset=0&count=20" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Step 3: Create a Playlist

Playlists are the core social object — users create them, share them publicly, and other users can discover and collect them.

3a. Create the Playlist

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/playlists

curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/playlists" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "Friday Night Vibes",
    "Description": "Weekend warm-up mix",
    "IsPublic": true
  }'

Save the playlist ID from the response.

3b. Add Tracks

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/playlists/{playlistId}/tracks

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

3c. Upload Cover Art (Optional)

Endpoint: PUT https://api-services-connect.tunedglobal.com/api/v3/playlists/{playlistId}/image/cover

curl -X PUT "https://api-services-connect.tunedglobal.com/api/v3/playlists/88001/image/cover" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@cover.jpg"

Step 4: Follow Artists

Build a personalised feed by following artists.

Endpoint: PUT https://api-services-connect.tunedglobal.com/api/v3/collection/followedartists/{artistId}

curl -X PUT "https://api-services-connect.tunedglobal.com/api/v3/collection/followedartists/12345" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Follow multiple artists in one call:

Endpoint: PUT https://api-services-connect.tunedglobal.com/api/v3/collection/follow-artists

curl -X PUT "https://api-services-connect.tunedglobal.com/api/v3/collection/follow-artists" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[12345, 12346, 12347]'

Check if the user is already following an artist:

GET /api/v3/collection/followedartists/{artistId}/exists

Step 5: Discover Community Content

Surface playlists and profiles created by other users.

Search user profiles:

curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/search/users?q=DJ%20Mike&count=10" \
  -H "StoreId: YOUR_STORE_ID"

Browse a user's public playlists:

curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/public?userId=67890&count=20" \
  -H "StoreId: YOUR_STORE_ID"

Browse verified user playlists:

curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/playlists/verified?count=20" \
  -H "StoreId: YOUR_STORE_ID"

Add a community playlist to the user's collection:

curl -X PUT "https://api-services-connect.tunedglobal.com/api/v3/collection/playlists/88001" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Expected Results

After completing this quick start you should have:

  • Tracks saved in the user's personal collection
  • A public playlist with tracks and optional cover art
  • Artists followed in the user's profile
  • Community playlists discovered and added to the user's collection
  • HTTP 200 responses on all endpoints with valid payloads

Troubleshooting

Error                    Cause                                Solution
-----------------------  -----------------------------------  ------------------------------------------
401 Unauthorized         Missing or invalid Bearer token      Re-authenticate (Step 1)
403 Forbidden            User lacks permission                Check subscription and StoreId
404 on playlist          Invalid playlist ID                  Verify ID from the create response
Empty search results     No matching user profiles            Try broader search terms

What's Next

  • Full API reference — see the Social & UGC guide for all playlist CRUD operations, collection management across all content types, and user context endpoints
  • UGC Video — coming soon: video submission API with HLS output at 1080p, 720p, 480p, and 360p
  • Social Radio — SDK for live broadcasting with audience interaction, tipping, and AutomixIQ transitions
  • AutomixIQ — AI-powered DJ transitions between tracks, available as an SDK for Android and iOS

Quick Reference — Headers

Header          Value                               Required By
--------------- ----------------------------------- ----------------------------
StoreId         Your Tuned Global store identifier  All endpoints
Authorization   Bearer <access_token>               All Services API (v3) endpoints
Content-Type    application/json                    POST/PUT requests
Country         ISO country code (e.g. AU)          Metadata search endpoints

Notes

Replace YOUR_STORE_ID, YOUR_ACCESS_TOKEN, TEST_USER, TEST_PASSWORD, and example IDs with your actual credentials from Tuned Global. Services API endpoints use v3. Metadata API endpoints use v2.4.

← Previous Image Handling

On this page