Quickstart and Documentation

This API is a RESTful service for music metadata. In this quickstart guide, we'll be going over some of the functionality, authenticating, and how to make your first queries.

Authentication

There are two ways to authenticate with the API: demo codes and bearer tokens.

Demo Codes

Demo Codes are limited-use codes that you can ask our sales team for. They are mainly used on the main demo page to sample some data, but you can also make custom calls with them in case you want to test a server-to-server implementation since it has the same response body as a bearer token.

To get a long-usage demo code, please contact our sales team.

Using a demo code in a request is as simple as appending it to the querystring of your request. Let's say you want to find songs made by Counting Crows; your request using cURL would look something like:


curl -X GET \
  "https://api.cultofrai.com/api/v1.0/resolve\
  ?artistName=Counting%20Crows\
  &demoCode=XXXX-XXXX"
          

Bearer Tokens

Bearer tokens are used once you have an account with us and are primarily for server-to-server authentication. The bearer token is passed in via the Authorization header and is formatted as Bearer your-token-here. The same request above with a bearer token in curl would look something like:


curl -X GET \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.cultofrai.com/api/v1.0/resolve?artistName=Counting%20Crows"
          

Resolution

Resolution is a lookup of track metadata. In the above example, we simply looked up any song by Counting Crows, but other constraints can be placed to narrow results. A full list of possible parameters are available in the API documentation linked at the end of this document.

Multiple Query Parameters

You can mix-and-match query values to restrict results. For example, if you want to find songs on Stone Temple Pilots' "Purple" album:


curl -X GET \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.cultofrai.com/api/v1.0\
  /resolve?artistName=Stone Temple Pilots&albumTitle=Purple
          

Restricting Returned Fields

To limit the amount of data returned, you can pass a comma-delimited list of fields you'd like to have returned. For example, if you would like the title, ISRC, and the musical work title and writer information:


curl -X GET \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.cultofrai.com/api/v1.0\
  /resolve?artistName=Stone Temple Pilots\
  &fields=title,isrc,musicalWorks.writers,musicalWorks.title
          

Pagination

The returned array can be paginated. The default limit is 25 records per response. You can specify more or less and iterate through them with the limit and skip parameters, like so:


curl -X GET \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.cultofrai.com/api/v1.0\
  /resolve?artistName=Stone Temple Pilots\
  &limit=10&skip=20
          

Caching

Currently, all calls made to the resolution endpoint with a bearer token are cached for a year. This allows you to look at data that has been queried in the past without incurring a fee for calling it again.

Each response you get will have a meta object that contains a responseId, which is the unique identifier for that response. Simply pass it to the cache endpoint like so:


curl -X GET \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.cultofrai.com/api/v1.0\
  /cache/xxxxxxxxxxxxxxxxxxxx
          

If you lost the responseId, you can get a range of responseIds made in the past by querying the cache endpoint itself. You must provide a time range. To get the 51-100th responseIds made in the month of March 2019, you would format your query as:


curl -X GET \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://api.cultofrai.com/api/v1.0\
  /cache?start=2019-03-01T00:00:00Z&end=2019-03-31T23:59:59\
  &limit=50&skip=50
          

Parsing

The parsing functionality uses machine learning to extrapolate classical music metadata from their titles. It's a POST request, so the title is passed in the body:


curl -X POST \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"
  -d '{"title":"Symphony No. 40, 1st Movement \"Allegro\""}'
  "https://api.cultofrai.com/api/v1.0/parse"