Getting Started

With the Epidemic Sound Connect API, you can offer your users the perfect soundtrack for their content. This guide will walk you through the steps to authorize your app, fetch available collections with their tracks, and download a track.

Workflow steps

1. Authorize your app
2. List collections with their tracks
3. Download a track

Authorize your app

You may use the api access credentials to authorize your app and start exploring the API's capabilities.

Every call to Epidemic Sound Connect API must include a user access token. Epidemic Sound Connect API supports two types of end-user tokens. For the existing Epidemic Sound users, you could use OAuth/OpenID to retrieve an access token for each user. This process is described in detail in this section. Using the Epidemic Sound Connect token allows the app to retrieve personalised content, for instance, user-liked tracks. Reach out to us if you would like to integrate with Epidemic Sound to get access to the extended list of features.

In this guide, we will focus on the scenario when the app is dealing with a user who doesn’t have an Epidemic Sound account yet. Obtaining the token in this case consists of two steps where a Partner Access Token is generated first and is used later to retrieve the token for the specific user. First, you must generate a partner access token using your app Access Key and Access Key Secret. This will allow you to authorize your application to fetch a user access token.

Fetching a partner token

curl -X 'POST' \
  'https://partner-content-api.epidemicsound.com/v0/partner-token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "accessKeyId": "{access_key_id}",
  "accessKeySecret": "{access_key_secret}"
}'

Example partner token response

{
  "accessToken": "eyJ0eXAi…"
}

For analytics and security purposes we require a unique user id to be provided for end users. You can use any string as long as it stays unique per user.

Fetching a user token

curl -X 'POST' \
  'https://partner-content-api.epidemicsound.com/v0/token' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {Partner Token}' \
  -d '{
  "userId": "d6bbf89b-56da-49c5-b3f1-252f61a34970"
}'

Example user token response

{
  "accessToken": "xjOx…"
}

List collections with their tracks

Each application comes with a default list of collections and tracks. You can change your collections in the developer portal. Use the collections endpoint to list your collections and the first few tracks of each collection.

Listing collections

curl -X 'GET' \
  'https://partner-content-api.epidemicsound.com/v0/collections' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {User Access Token}’

Example collections response

{
  "collections": [
    {
      "id": "7a84d049-057a-46fb-93d1-eace263d8973",
      "name": "Lounge",
      "tracks": [
        {
          "id": "Mj0MGDIRZm",
          "title": "Solaris",
          "mainArtists": [
            "Marc Torch"
          ],
          "featuredArtists": [],
          "bpm": 110,
          "length": 178,
          "moods": [
            {
              "id": "epic",
              "name": "Epic"
            },
            {
              "id": "hopeful",
              "name": "Hopeful"
            }
          ],
          "genres": [
            {
              "id": "2010s-rock",
              "name": "2010s Rock",
              "parent": {
                "id": "rock",
                "name": "Rock"
              }
            },
            {
              "id": "post-rock",
              "name": "Post Rock",
              "parent": {
                "id": "rock",
                "name": "Rock"
              }
            }
          ],
          "images": {
            "default": "https://cdn.epidemicsound.com/curation-assets/commercial-release-cover-images/4661/300x300.jpg",
            "XS": "https://cdn.epidemicsound.com/curation-assets/commercial-release-cover-images/4661/128x128.jpg",
            "S": "https://cdn.epidemicsound.com/curation-assets/commercial-release-cover-images/4661/300x300.jpg",
            "M": "https://cdn.epidemicsound.com/curation-assets/commercial-release-cover-images/4661/600x600.jpg",
            "L": "https://cdn.epidemicsound.com/curation-assets/commercial-release-cover-images/4661/1050x1050.jpg"
          },
          "waveformUrl": "https://pdn.epidemicsound.com/waveforms/1600/331261.json",
          "isExplicit": false,
          "hasVocals": false,
          "added": "2020-02-12",
          "isPreviewOnly": false,
          "tierOption": "FREE"
      }
  ],
  "pagination": {
    "page": 1,
    "limit": 10
  },
  "links": {
    "next": "/v0/collections?limit=10&offset=10",
    "prev": null
  }
}

Download a track

You are now just one call away from downloading the audio file. Use the trackId from the previous call to get a download link to the actual media file from our CDN.

Download a track

curl -X 'GET' \
   'https://partner-content-api.epidemicsound.com/v0/tracks/{Track ID}/download?format=mp3&quality=low' \
   -H 'Accept: application/json' \
   -H 'Authorization: Bearer {User Access Token}'

Example track download response

{
  "url": "https://d37sjn4j2x9ce8.cloudfront.net/ES_ITUNES/Solaris/ES_Solaris.mp3?Expires=1666691372&Signature=eUU4M5v…XKQ__&Key-Pair-Id=K344YJTI5162TY",
  "expires": "2022-10-25T09:49:32Z"
}

The returned URL link is set to expire. The user has to start the download before the link expires. To optimise the user’s bandwidth usage you might choose to download lower-quality files by setting the quality parameter to low.

What’s next?

Read more on how you can access collection details and explore all the music available within a collection.