Content Services

Audiogum supports search, browse, authentication and playback across a broad range of content services as well as our own catalogue of artists.


As music service functionality and availability varies, we offer a configuration API that returns details about which services are available as well as their capabilites.

GET /v1/configGets various country-specific configuration such as which music services are supported.

Example service config

GET /v1/config

  "services": [ // services for this country
      "id": "tidal",
      "name": "TIDAL",
      "capabilities": [
      "upsell": {
        "type": "signin"
      "searchtypes": [
      "playback": {
        "account": "signin",
        "subscription": [
        "requires": "http",
        "timelimited": 300
  "countrycode": "gb"


Services are marked as having certain "capabilities" that indicate which APIs can be used with them:

browseService supports browsing content through nested lists with or without a user account. The GET /v1/browse/{service} API allows you to get the top-level lists and drill down into each list, until there are content items that may be played. See Search and Browse below for more information about this API.
dynamicplaylistService supports creation of Audiogum dynamic playlists.
listtracksService supports listing playlist or album tracks
localsaveplaylistService supports app SDK creation of playlists
radiobrowseAs with browse, the service has browsable content through the GET /v1/browse/{service} API, but the content is either traditional radio or radio-style playlists. Services that support radiobrowse will also be marked as supporting browse, but this gives a finer level of detail if required by your UI. See Browse below for more information about this API.
remoteplaybackService supports remotely starting playback on a device. A list of devices available to the user can be obtained through GET /v1/user/{service}/devices and playback can be started through PUT /v1/user/{service}/devices/{deviceid}/player. The main example of this capability is Spotify, where Spotify Connect speakers can be listed and used to start playback of content.
searchService supports searching for content. The Audiogum configuration specifies the types of content searchable for each service and allows searching for specified types. The GET /v1/content API supports searching across multiple services simultaneously and returns content in a consistent format. See Search below for more information about this API.
signinService requires a user account for playback of content and sign-in to the service should be offered in application settings. Once sign in is achieved, the user’s account on the service is “linked” to the user’s Audiogum account. Signin is an OAuth2 flow that is started by calling GET /v1/user/{service}/authorize in an embedded web browser or using an OAuth2 library and POST /v1/user/{service}/token to retrieve an access_token - see authentication below.
signinbrowseService requires a user account for browsing and searching content. The user cannot browse this service until their account on the service is "linked" to their Audiogum account (see signin capability).
sdksigninService requires a user account for playback of content and sign-in to the service should be offered in application settings. Once sign in is achieved, the user’s account on the service is “linked” to the user’s Audiogum account. Signin is achieved through a client SDK. POST /v1/user/{service}/token is used to store the access_token.
userplaylistsService supports listing the playlists belonging to or followed by the user on the service.
saveplaylistService supports creation of playlists through the POST /v1/user/{service}/playables/{id} api

You can see the capabilities of each service on our availability page.


The playback part of the service configuration describes what is needed to play content:

accountIf signin is present, the user is required to sign in with a music service account - the method of signin is detailed in the service capabilities.
launcherService requires playback through their app. In this case, Audiogum still offers the ability to search and browse content, but the service's app must be used to play content. The value of launcher in the configuration gives the field to use to deep link into the service's app. For example, with Spotify, the ref field is used. For dynamic personalised playlists in the case of launcher services, the API allows an Audiogum generated playlist to be created and stored on the service for playback as a playlist.
platformIf present, indicates that playback is restricted only to the named platforms. For example, Apple Music is only available with an SDK on iOS.
requiresThe client playback requirements - will be one of:
  • http, https (HTTP-based progressive download supported)
  • local - the content will have local URIs that have been sent for user catalogue matching by the manufacturer - e.g. smb://... or file://...
  • sdk - an SDK from the music service is required
  • video when the content requires visual output
For services offering HTTP(S) streaming, playables data will include the stream URL.
requirescertificationIndicates that a service requires certification of the experience before allowing user access - this flag allows clients to hide such services to only show in test versions of apps and explicitly white-list access once certification has passed.
sendanalyticsIndicates that the service mandates sending of playback analytics.
subscriptionIf present, means that a subscription is required - an array of subscription levels is given in the configuration and one of those should match the subscription attribute returned by the user details API.
timelimitedThe content of an HTTP(S) stream is time limited - this configuration value is the time in seconds that a URL is valid for.

You can see the requirement of each service on our availability page.

The Search APIs allow your users to find relevant content quickly and also drill down into details to explore further.

GET /v1/contentSearch across music services for content. Returns search results in various "buckets" - e.g. Playlists, Radio Stations, Artists.
GET /v1/content/{type}/{service}Drill down into detailed results for paging through a 'bucket'. The service configuration shows which types are supported with the searchtypes attribute.
GET /v1/content/{type}Drill down into detailed results across services for paging through a 'bucket'.


The Browse API lets your users explore content from various music services. It returns a list of items of type category which can be explored with the ultimate goal of drilling down to items that aren't a category that can be played such as internetradio, audiobook or playlist. To explore a category, pass it's ref to this API in the parent parameter. Some services will return nested items within the category meaning no callback is required to explore further.

GET /v1/browse/{service}Browse playlists and internet radio stations from music services.

Where available, the Browse API provides hints to indicate the content contained within a category with the childtheme and childtype properties to allow display of iconography in your browse experience. Alternatively, some services support browse images which will be returned in an images object.

childtheme values

newThe child items are new releases
chartThe child items are chart or popular
featuredThe child items are featured editorial content
locationThe child items are location based
personalThe child items are selected or created by the user, such as user playlists
genreThe child items are genres or genre-themed
moodThe child items are moods or mood-themed
mixedThe child items are undeterminable or a mixture of the above

childtype values

albumThe child items are music albums
artistThe child items are music artists
authorThe child items are podcast or audiobook authors
audiobookThe child items are audiobooks
categoryThe child items are further categories
displayThe child items are textual display items
internetradioThe child items are internet radio stations
playlistThe child items are music playlists
podcastThe child items are podcasts
podcastepisodeThe child items are podcast episodes
radioplaylistThe child items are radio-style music playlists
singleThe child items are music singles
songThe child items are music songs
userThe child items are other users of the service


Where a music service offers authentication, Audiogum simplifies your integration with a consistent approach to signing in and user management. Typically, services allow sign-in through an OAuth2 flow where the user can securely sign in and grant permission without giving up their username or password.

Once a user is authenticated with a service, the service account is “linked” to the Audiogum user account and the access token is maintained by Audiogum service. This allows subsequent searching and browsing of the music service content via Audiogum API on behalf of the user without further authentication by the user.

Linked services also allow devices to request content from a service via the Audiogum Playables API without the device needing the user’s service credentials.

GET /v1/user/linkedservicesGets details about all of the user's associated service accounts.
GET /v1/user/{service}/authorizeGet a URI to pass to a web browser to start a sign-in flow. Audiogum constructs the URI including requesting appropriate permissions.
POST /v1/user/{service}/tokenThis associates music service access details by taking the authorization_code from the end of the above sign-in flow.
GET /v1/user/{service}Gets details about the user's associated account.
DELETE /v1/user/{service}/tokenRemoves access for a service.
GET /v1/{service}/logo.pngGet the logo for a music service.
GET /v1/{service}/playerlogo.pngGet a smaller logo for a music service suitable to display on a now-playing screen.

Client OAuth2 Libraries

To help your app implement the OAuth2 signin for services, we have used and would recommend the following libraries:

AndroidAndroid OAuth Client Library

Taste Profile import

Once the user has authenticated with the service, you can optionally add to their taste profile by importing taste preferences from the service. The POST /v1/user/taste/import/{service} API is used to automatically add to the user's taste profile when data is available from the service.

Service Availability

You can find the full list of content services Audiogum has integrated with on our availability page.