Quickstart
Outcome
This quickstart demonstrates end-to-end music streaming API integration, covering authentication through playback logging
Step you will complete
Auth → Retrieve user profile → Search the catalogue → Retrieve metadata → Stream track → Log playback
Timed required
~10-15 minutes
Prerequisites
- API keys from Tuned Global
- Postman workspace configured
- Test user account credentials
Step-by-step implementation
1
Authenticate
Request a JWT token from the authentication server using test credentials.
Purpose: Establishes user session within the system.
👉 Endpoint: api-authentication-connect.tunedglobal.com/oauth2/token
Example:
curl --location 'https://api-authentication-connect.tunedglobal.com/oauth2/token' \
--header 'StoreId: XXYY' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=testUserName' \
--data-urlencode 'password=testPassword'
2
Retrieve user profile
Fetch account subscriptions and device information.
Purpose: Determines user access rights and playback restrictions.
👉 Endpoint: GET /api/v3/users/{user_id}/profile
Example:
curl --location 'https://api-services-connect.tunedglobal.com/api/v3/users/{user_id}/profile' \
--header 'StoreId: XXYY' \
--header 'Authorization: Bearer xxxyyyy'
Returns:
- Active subscriptions
- Registered devices
- Basic user profile information
3
Search catalogue
Find tracks using flexible search endpoints supporting:
- ISRC codes
- Genre filters
- Artist names
- Track titles with duration
- Advanced metadata filters
Purpose: Mirrors user discovery patterns.
👉 Endpoint: GET /api/v2.4/search/songs
Example:
curl --location 'https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs?q=Bohemian%20Rhapsody' \
--header 'StoreId: XXYY'
4
Retrieve metadata
Obtain detailed information for selected tracks, albums, and artists.
Track Metadata: Endpoint returns track name, artist, duration, and metadata fields.
Album Metadata: Returns album title, artist, artwork, and release information.
Artist Metadata: Returns artist name and imagery.
Image Optimisation: Use image engine to generate appropriately-sized artwork for UI performance.
5
Get stream URL (Stream a track)
Request signed streaming URL for playback.
Purpose: Validates entitlements and device-level rights enforcement.
👉 Endpoint: POST /api/v3/plays/1001/987654/stream
Required Inputs:
- Tuned Global Track ID
- Device ID
- Bearer authentication token
Example:
First request a token > Then get stream URL
curl --location --request POST \
'https://api-services-connect.tunedglobal.com/api/v3/plays/1001/987654/stream?streamType=Music&streamProvider=Tuned' \
--header 'StoreId: XXYY' \
--header 'Authorization: Bearer xxxyyyy'
6
Log playback
Submit playback events for analytics and royalty reporting.
👉 Endpoint: POST /api/v3/plays/1001
Example:
curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/plays/1001" \
-H "StoreId: XXYY" \
-H "Authorization: Bearer xxxyyyy" \
-H "Content-Type: application/json" \
-d '{
"TrackId": 987654,
"LogPlayType": "Start",
"Seconds": 0,
"Source": "Album",
"SourceId": 12345,
"Country": "AU",
"PlayerType": "MobilePhone"
}'
Recommended Events:
- Play start
- 30-second milestone (mandatory for reporting)
- Skip events with timestamps
- End of file
Expected results
- Audio playback functionality
- Play history entries recorded
- Playlist creation confirmed
- HTTP 200 responses with valid payloads
- Streaming URLs with valid expiration
- Play log entries for user and track
Troubleshooting
- 403 on playback: Token expired or user not entitled. Re-authenticate; check subscription/package status.
- Missing play logs: Verify timestamps, user ID, and duration threshold.
- Empty playlist: Check track ID scope and user permissions; retry add-item.
On this page
- Quickstart