Skip to main content

Using Profiles

This tutorial will explain how to utilize user profiles within our API. It is designed to help you understand and make the most of the profile functionalities we offer, enabling you to save favorites and access your interaction history for a tailored experience.

About Profiles​

When obtaining your authorization token, a device ID is passed to the authorization endpoint. This unique identifier ties your favorites and history to your specific device. It's important to note that if your device ID changes, you will not be able to access the profile associated with the previous device, as the profile information is linked directly to the ID you provide.

Prerequisites​

Before you begin, make sure you have:

  • The authentication credentials required to access the API.
  • Familiarity with HTTP methods and response codes.

Favorites​

Adding a Favorite​

To add an item to your favorites, you need to send a PUT request to the /api/v2/favorites endpoint.

This request should include a JSON body with two parameters:

  • assetId: The unique identifier for the item you wish to favorite
  • contentType: The type of content you are favoriting.

The admissible content type are: STATION, AUDIOBOOK, PODCAST, PODCAST_EPISODE

curl -X PUT "https://music-service.stingray.com/api/v2/favorites" -H "Authorization: Bearer YOUR_JWT" -d '{"assetId": "007", "contentType": "STATION"}'

Retrieving Your Favorites​

To view your list of favorited items, issue a GET request to /api/v2/favorites.

The contentType parameter is required to filter the favorites by the type of content.

curl -X GET "https://music-service.stingray.com/api/v2/favorites?contentType=STATION" -H "Authorization: Bearer YOUR_JWT"

This endpoint also supports pagination, allowing you to retrieve a subset of results at a time. To paginate your results, include the query parameters limit for the number of items you wish to receive and offset for the starting position in your list. Note that the favorite items are returned in the reverse order of their addition, following a Last In, First Out (LIFO) sequence.

curl -X GET "https://music-service.stingray.com/api/v2/favorites?contentType=STATION&offset=5&limit=10" -H "Authorization: Bearer YOUR_JWT"

Deleting a Favorite​

If you decide to remove an item from your favorites, you can do so by making a DELETE request to /api/v2/favorites/{id}, where {id} is the identifier of the asset you want to unfavorite.

You must also provide the contentType query parameter to ensure the correct asset type is being deleted.

curl -X DELETE "https://music-service.stingray.com/api/v2/favorites/007?contentType=STATION" -H "Authorization: Bearer YOUR_JWT"

Deleting all Favorites​

It is also possible to remove every favorite at once by making a DELETE request to /api/v2/favorites.

This endpoint take an optional contentType query parameter that represent the type of content to delete. When left empty, every favorite will be removed.

curl -X DELETE "https://music-service.stingray.com/api/v2/favorites" -H "Authorization: Bearer YOUR_JWT"

Validating a Favorite​

To check if a specific item is in your favorites, perform a HEAD request to /api/v2/favorites/{id}, where {id} is the asset identifier. You must also include the contentType query parameter.

curl -X HEAD "https://music-service.stingray.com/api/v2/favorites/007?contentType=STATION" -H "Authorization: Bearer YOUR_JWT"

A successful check will return a response code of 200, indicating that the asset is indeed in your favorites. Conversely, a response code of 404 signifies that the asset is not a favorite.

History​

Adding to History​

To add an item to your history, you will use a similar PUT request as you did for adding a favorite, but to /api/v2/history:

This request must also include a JSON body with two parameters:

  • assetId: The unique identifier for the item you wish to add to the history.
  • contentType: The type of content of the item being added to the history.

The admissible content type are: STATION, AUDIOBOOK, PODCAST_EPISODE

curl -X PUT "https://music-service.stingray.com/api/v2/history" -H "Authorization: Bearer YOUR_JWT" -d '{"assetId": "007", "contentType": "STATION"}'

Retrieving Your History​

To view your play history, issue a GET request to /api/v2/history.

This request can also be paginated with the limit and offset query parameters to retrieve a subset of the history. note that the history items are returned in the reverse order of their addition, following a Last In, First Out (LIFO) sequence.

curl -X GET "https://music-service.stingray.com/api/v2/history?offset=5&limit=10" -H "Authorization: Bearer YOUR_JWT"

Deleting from History​

To remove an item from your history, you will make a DELETE request to /api/v2/history/{id}, where {id} is the identifier of the asset.

The contentType query parameter is also required to delete the right asset.

curl -X DELETE "https://music-service.stingray.com/api/v2/history/007?contentType=STATION" -H "Authorization: Bearer YOUR_JWT"

Deleting all History​

Similar to favorite, it is also possible to delete every history at once by making a DELETE request to /api/v2/history.

This endpoint take an optional contentType query parameter that represent the type of content to delete. When left empty, all history items will be removed.

curl -X DELETE "https://music-service.stingray.com/api/v2/history" -H "Authorization: Bearer YOUR_JWT"

Conclusion​

It should now be easier to enrich the user experience by creating personalized and efficient interactions and ensuring that users' most valued content is always at their fingertips.