NAV Navbar
curl
  • Introduction
  • Authentication
  • Errors
  • Pagination
  • Specification
  • Resources
  • Artists
  • Audio Files
  • Songs
  • Tags
  • Introduction

    Welcome to the Soundstripe API! You can use our API to access endpoints which can get information on songs, tags, and more.

    Authentication

    To authorize, use this code:

    # You must pass the following headers with each request
    curl "api_endpoint_here"
      -H "Authorization: Token YOURAPIKEY"
      -H "Content-Type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
    

    Make sure to replace YOURAPIKEY with your API key.

    Soundstripe uses API keys to allow access to the API. Please contact us to set up your account for API access.

    Soundstripe expects for the API key to be included in all API requests to the server as a Token in the Authorization header:

    Authorization: Token YOURAPIKEY

    All requests require the following additional headers as well:

    Errors

    If an error happens, we will return an errors key that contains an array of the relevant errors.

    The errors array

    {
      "errors": [
          {
              "detail": "Couldn't find Song with 'id'=1000",
              "status": 404
          }
      ]
    }
    

    Attributes

    Parameter Type Description
    detail string Information about the specific error
    status integer HTTP status code

    Error status codes

    The Soundstripe API uses the following HTTP statuses:

    Status Meaning
    400 Bad Request -- Something about your request was malformed.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- You do not have access to the requested endpoint.
    404 Not Found -- The specified resource could not be found.
    406 Not Acceptable -- The request failed to complete properly.
    500 Internal Server Error -- We had a problem with our server. Try again later and contact us if this persists.

    Pagination

    All top-level API resources that have support for "list" calls are paginated. For instance you can list songs. These list API methods share a common structure, taking two optional parameters nested under a page key: size and number.

    List endpoints also return a top-level links key that allows you to easily traverse the list.

    Query String Parameters

    Parameter Default Description
    page[size] 10 The number of results from 1-100 to return.
    page[number] 1 The page to return, one-indexed.

    These are the keys nested under the links key in a list endpoint's JSON response

    Key Description
    self The current request URL
    first The first page of the list as constructed by the specified (or default) pagination parameters
    prev The previous page of the list as constructed by the specified (or default) pagination parameters
    next The next page of the list as constructed by the specified (or default) pagination parameters
    last The last page of the list as constructed by the specified (or default) pagination parameters
    meta An object containing additional data. Currently the only nested key is total_count, which is the number of results in the requested list across all pages

    Specification

    Our API follows the JSONAPI specification, found here: http://jsonapi.org. If you're familiar with the specification, the API should be fairly self-explanatory. Outside of any route- or parameter-specific questions that will be answered in this documentation, any other questions you may have will be answered by the specification.

    Resources

    Artists

    Artists are attached to songs, and provide information about the artist, including an image URL.

    The artist object

    {
      "id": "1",
      "type": "artists",
      "attributes": {
        "name": "Ice Cold Cayenne Poppers",
        "image": "https://soundstripe.example.com/ICCP.png?w=100&h=100",
      }
    }
    

    Attributes

    Parameter Type Description
    name string Artist name
    image string Image URL. The w and h parameters (both 100px by default) can be updated to change the width and height of the image, respectively. Removing these parameters will return the full-resolution image.

    Audio Files

    Audio files are attached to songs, and provide information about the file itself, links to different versions (.mp3, .wav), etc.

    The audio file object

    {
      "id": "1",
      "type": "audio_files",
      "attributes": {
        "description": "Instrumental [Primary]",
        "duration": 20.18975,
        "instrumental": true,
        "versions": {
          "mp3": "https://soundstripe.example.com/mp3_the_dread.mp3",
          "wav": "https://soundstripe.example.com/the_dread.wav"
        },
      }
    }
    

    Attributes

    Parameter Type Description
    description string Audio file description
    duration number Duration in seconds
    instrumental boolean Whether or not this audio file has vocals
    versions object
    • mp3 [string]: .mp3 URL. Useful for previewing or when minimizing file size is important, such as for previewing or access on mobile devices.
    • wav [string]: .wav URL. Useful when film-standard audio resolution is required (48kHz/24-bit).
    Note: Links expire within 1 hour.

    Songs

    Songs are the main resource in Soundstripe. Songs will have one or more audio files attached to them.

    The song object

    {
      "id": "1",
      "type": "songs",
      "attributes": {
        "bpm": 110.0,
        "explicit": false,
        "key": {
          "name": "A",
          "mode": "major",
        },
        "tags": {
          "characteristic": [
            "Minimal",
            "Droning"
          ],
          "genre": [
            "Soundtrack / Cinematic"
          ],
          "instrument": [
            "Strings",
            "Ambient Tones"
          ],
          "mood": [
            "Scary",
            "Suspenseful"
          ]
        },
        "title": "The Dread"
      },
      "relationships": {
        "artists": {
          "data": [
            {
              "id": "1",
              "type": "artists"
            }
          ]
        },
        "audio_files": {
          "data": [
            {
              "id": "1",
              "type": "audio_files"
            }
          ]
        }
      }
    }
    

    Attributes

    Parameter Type Description
    bpm number Song BPM
    key string Song's musical key.
    • name [string]: The name of the key. For instance, "Ab/G#".
    • mode [string]: The key's mode. For instance, "major".
    explicit boolean Whether or not the song has explicit lyrics.
    tags object Tag names by category.
    • characteristic [array]: Characteristics
    • genre [array]: Genres
    • instrument [array]: Instruments
    • mood [array]: Moods
    title string Song title

    List songs

    curl "https://api.soundstripe.com/v1/songs"
      -H "Authorization: Token YOURAPIKEY"
      -H "Content-Type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": "1",
          "type": "songs",
          "attributes": {
            "bpm": 110.0,
            "explicit": false,
            "key": "A Major",
            "tags": {
              "characteristic": [
                "Minimal",
                "Droning"
              ],
              "genre": [
                "Soundtrack / Cinematic"
              ],
              "instrument": [
                "Strings",
                "Ambient Tones"
              ],
              "mood": [
                "Scary",
                "Suspenseful"
              ]
            },
            "title": "The Dread"
          },
          "relationships": {
            "artists": {
              "data": [
                {
                  "id": "1",
                  "type": "artists"
                }
              ]
            },
            "audio_files": {
              "data": [
                {
                  "id": "1",
                  "type": "audio_files"
                }
              ]
            }
          }
        },
        . . . more results . . .
      ],
      "included": [
        {
          "id": "1",
          "type": "artists",
          "attributes": {
            "name": "Ice Cold Cayenne Poppers",
            "image": "https://soundstripe.example.com/ICCP.png?w=100&h=100",
          }
        },
        {
          "id": "1",
          "type": "audio_files",
          "attributes": {
            "file_extension": "wav",
            "description": "Instrumental [Primary]",
            "duration": 20.18975,
            "exclusions": [],
            "versions": {
              "mp3": "https://soundstripe.example.com/mp3_the_dread.mp3",
              "wav": "https://soundstripe.example.com/the_dread.wav"
            },
            "vocal_degree": "instrumental"
          },
        },
          . . . more artists and audio files . . .
      ],
      "links": {
        "self": "http://api.soundstripe.com/v1/songs?page%5Bsize%5D=10&page%5Bnumber%5D=1",
        "first": null,
        "prev": null,
        "next": "http://api.soundstripe.com/v1/songs?page%5Bsize%5D=10&page%5Bnumber%5D=2",
        "last": "http://api.soundstripe.com/v1/songs?page%5Bsize%5D=10&page%5Bnumber%5D=450",
        "meta": {
          "total_count": 4500
        }
      }
    }
    

    This endpoint retrieves a list of songs. It also includes the associated artists and audio files of each song. The first artist listed under each song's relationships.artists is the primary artist. The first audio file listed under each song's relationships.audio_files is the primary audio file. By default, only the primary audio file of each song is included in the response in order to limit response size. To include all audio files for each song in the response, set the URL parameter filter[include_alternate_audio_files] to true.

    HTTP Request

    GET https://api.soundstripe.com/v1/songs

    Query String Parameters

    Parameter Type Default Description
    filter[bpm][min] integer null Minimum BPM
    filter[bpm][max] integer null Maximum BPM
    filter[duration][min] integer null Minimum duration of the song's primary audio file
    filter[duration][max] integer null Maximum duration of the song's primary audio file
    filter[duration][consider_alternate_audio_files] boolean false If true, songs will be returned if any of their audio files (not just the primary audio file) match the supplied duration min, max, or both (whatever is supplied). If false, songs will be returned if their primary audio file matches the supplied duration min, max, or both (whatever is supplied). Only active when used with duration min, max, or both.
    filter[energy] string null Energy to filter by. One of: very_low, low, medium or high.
    filter[include_alternate_audio_files] boolean false If true, all audio files for each song will be returned in the audio_files relationship, and in the top-level included key. If false, only primary audio files will be returned in the audio_files relationship, and in the top-level included key. By default, this is false, because response size can be large when including all audio files for each song.
    filter[instrumental] boolean null If true, only show songs that have at least one instrumental audio file. If false, don't show songs with instrumental audio files.
    filter[q] string null Search query
    filter[tags][characteristic] string null Comma-separated characteristic tags to filter by. Tag IDs or names can be used interchangeably to filter. If a tag ID or name is prefixed with a hyphen (-), songs with that tag will be filtered out. To get a list of all possible characteristic tags, see the list tags endpoint.
    filter[tags][genre] string null Comma-separated genre tags to filter by. Tag IDs or names can be used interchangeably to filter. If a tag ID or name is prefixed with a hyphen (-), songs with that tag will be filtered out. To get a list of all possible genre tags, see the list tags endpoint.
    filter[tags][instrument] string null Comma-separated instrument tags to filter by. Tag IDs or names can be used interchangeably to filter. If a tag ID or name is prefixed with a hyphen (-), songs with that tag will be filtered out. To get a list of all possible instrument tags, see the list tags endpoint.
    filter[tags][mood] string null Comma-separated mood tags to filter by. Tag IDs or names can be used interchangeably to filter. If a tag ID or name is prefixed with a hyphen (-), songs with that tag will be filtered out. To get a list of all possible mood tags, see the list tags endpoint.
    filter[vocals] boolean null If true, only show songs that have at least one vocal audio file. If false, don't show songs with vocal audio files.

    Retrieve a song

    curl "https://api.soundstripe.com/v1/songs/1"
      -H "Authorization: Token YOURAPIKEY"
      -H "Content-Type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
    

    The above command returns JSON structured like this:

    {
      "data": {
        "id": "1",
        "type": "songs",
        "attributes": {
          "bpm": 110.0,
          "explicit": false,
          "key": "A Major",
          "tags": {
            "characteristic": [
              "Minimal",
              "Droning"
            ],
            "genre": [
              "Soundtrack / Cinematic"
            ],
            "instrument": [
              "Strings",
              "Ambient Tones"
            ],
            "mood": [
              "Scary",
              "Suspenseful"
            ]
          },
          "title": "The Dread"
        },
        "relationships": {
          "artists": {
            "data": [
              {
                "id": "1",
                "type": "artists"
              }
            ]
          },
          "audio_files": {
            "data": [
              {
                "id": "1",
                "type": "audio_files"
              }
            ]
          }
        }
      },
      "included": [
        {
          "id": "1",
          "type": "artists",
          "attributes": {
            "name": "Ice Cold Cayenne Poppers",
            "image": "https://soundstripe.example.com/ICCP.png?w=100&h=100",
          }
        },
        {
          "id": "1",
          "type": "audio_files",
          "attributes": {
            "file_extension": "wav",
            "description": "Instrumental [Primary]",
            "duration": 20.18975,
            "exclusions": [],
            "versions": {
              "mp3": "https://soundstripe.example.com/mp3_the_dread.mp3",
              "wav": "https://soundstripe.example.com/the_dread.wav"
            },
            "vocal_degree": "instrumental"
          },
        },
      ],
    }
    

    This endpoint retrieves a song. It also includes all of the associated artists and audio files of each song. The first artist listed under each song's relationships.artists is the primary artist. The first audio file listed under each song's relationships.audio_files is the primary audio file.

    HTTP Request

    GET https://api.soundstripe.com/v1/songs/:song_id

    URL Parameters

    Parameter Description
    song_id The song's ID

    Prevent YouTube claims

    curl "https://api.soundstripe.com/v1/songs/1/digital_usages"
      -H "Authorization: Token YOURAPIKEY"
      -H "Content-Type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
      -d '{"data": { "type": "digital_usages" }}'
    

    The above command returns JSON structured like this:

    {
      "data": {
        "id": "1",
        "type": "digital_usages",
        "attributes": {
          "youtube_code": "somerandomstring"
        }
      }
    }
    

    This endpoint records a planned digital use of a song. Customers creating content for clients that will post videos to YouTube will clear content claims by generating a unique code for each song used in a video.

    For now this only applies to content uploaded to YouTube.

    HTTP Request

    POST https://api.soundstripe.com/v1/songs/:song_id/digital_usages

    URL Parameters

    Parameter Description
    song_id The song's ID

    POST Body

    The POST body must match the following:

    { "data": { "type": "digital_usages" } }

    Tags

    Tags are applied to songs to label their characteristics. They're useful for filtering song list requests. NOTE: Tag IDs or names can be used to filter songs.

    The tag object

    {
      "id": "8_bit",
      "type": "tags",
      "attributes": {
        "name": "8-bit",
        "category": "genre"
      }
    }
    

    Attributes

    Parameter Type Description
    name string Tag name
    category string Tag category. One of: characteristic, genre, instrument, or mood.

    List tags

    curl "https://api.soundstripe.com/v1/tags"
      -H "Authorization: Token YOURAPIKEY"
      -H "Content-Type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
    

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": "8_bit",
          "type": "tags",
          "attributes": {
            "name": "8-bit",
            "category": "genre"
          }
        }
        . . . more results . . .
      ],
      "links": {
        "self": "https://api.soundstripe.com/v1/tags?filter%5Btag_category%5D=Genre&page%5Bsize%5D=10&page%5Bnumber%5D=1",
        "first": null,
        "prev": null,
        "next": "https://api.soundstripe.com/v1/tags?filter%5Btag_category%5D=Genre&page%5Bsize%5D=10&page%5Bnumber%5D=2",
        "last": "https://api.soundstripe.com/v1/tags?filter%5Btag_category%5D=Genre&page%5Bsize%5D=10&page%5Bnumber%5D=5",
        "meta": {
          "total_count": 49
        }
      }
    }
    

    This endpoint retrieves a list of tags.

    HTTP Request

    GET https://api.soundstripe.com/v1/tags

    Query String Parameters

    Parameter Type Default Description
    filter[category] string null Category of tags to filter by. One of: characteristic, genre, instrument, or mood.