Cadenzabox API

Legacy documentation — 2019-02-25
Our new docs are here: docs.cadenzabox.com

Examples in this documentation are written using HTTPie.

To install httpie on macOS run brew install httpie.

The Cadenzabox API is designed to be a predictable and intuitive interface for interacting with a music catalogue and its tracks.

If you have a suggestion to improve this documentation or believe you’ve encountered a bug, please email [email protected].

REST API

# API endpoint (REST)
https://api.cadenzabox.com

We offer a REST API documeted in detail on these pages.

Required origin HTTP header
To select the desired catalogue, every request requires a valid Origin HTTP header.

# Required origin HTTP header
$ http GET "https://api.cadenzabox.com/tracks" \
  "Origin:$origin"

HTTP Header

Parameter	Description
`origin` Required	Your library’s full URL, including the protocol, e.g. `https://mylibrary.cadenzabox.com/`

WebSockets API

We also support WebSockets access. This is currently in use for all of our frontend library instances. Our WebSockets API is presently undocumented. Please email [email protected] if you are interested in using this API.

Authentication

The Cadenzabox API implements JSON Web Tokens (JWT) to allow users to log in to applications without exposing their credentials. The process involves an initial "login" request to obtain the token, then subsequent requests to the API which require authentication must supply the JWT as an Authorization HTTP header.

Acquire access token

# Standard authentication
# uses x-www-form-urlencoded method
$ http --form POST "https://api.cadenzabox.com/authentication" \
    "Content-Type:application/x-www-form-urlencoded" \
    "Origin:$origin" \
    "strategy=local" \
    "email=$email" \
    "password=$password"

# Alternate JSON authentication method
$ echo '{
        "strategy": "local",
        "email": "$email",
        "password": "$password"
    }' |  \
    http POST "https://api.cadenzabox.com/authentication" \
    "Content-Type:application/json" \
    "Origin:$origin"

Example response

{
    "accessToken": "eyJhbGciOiJIU[...]kcUyYv5TsH7U7ccHXM"
}

To acquire a JWT access token you must POST to the /authentication endpoint. We support x-www-form-urlencoded arguments or if you prefer, a JSON object of arguments if posting raw/application/json.

HTTP Headers

Parameter	Description
`origin` Required	Your library’s full URL, including the protocol, e.g. `https://mylibrary.cadenzabox.com/`

POST body arguments

Parameter	Description
`strategy` Required	Must be set to `local`.
`email` Required	The user’s email address.
`password` Required	The user’s password.

Authenticating requests

# Authenticated request for a user’s projects
$ http GET "https://api.cadenzabox.com/projects" \
    "Authorization:$authorization" \
    "Origin:$origin"

HTTP Headers

Parameter	Description
`origin` Required	Your library’s full URL, including the protocol, e.g. `https://mylibrary.cadenzabox.com/`
`authorization` Optional	The user’s JWT as acquired above.

Requests for a specific user’s data must be authenticated with a JWT access token supplied in the Authorization. Your client may only have one active access token at a time, per user. Acquiring a new access token will invalidate any other token you own for that user.

Pagination

Endpoints with enumerable objects support pagination.

Examples include tracks, releases, playlists, projects, etc.

# Pagination
$ http GET "https://api.cadenzabox.com/tracks?$skip=$skip&$limit=$limit" \
    "Origin:$origin"

# Example: page four, 10 items per page
https://api.cadenzabox.com/tracks?$skip=30&$limit=10

GET URL parameters

Parameter	Description
`skip` Optional	Denote which item to start from using a zero-based index. For example if you wanted page four and there were `10` items per page, you would “skip” over the first `30` items, i.e. skip the first three pages.
`limit` Optional	How many items you want returned past the starting point specified. Can be thought of as how many items “per page”.

Tracks

# Tracks
$ http GET "https://api.cadenzabox.com/tracks" \
    "Origin:$origin"

# Individual track
$ http GET "https://api.cadenzabox.com/tracks/$track_id" \
    "Origin:$origin"

Example response (individual track)

{
    "_id": "5bbf6d8c65e2610013050496",
    "title": "Kill 'Em All (Death Mix)",
    "versionTitle": "Death Mix",
    "description": "percussive action rock, thriller, dark, hybrid, orchestra, heavy metal guitars, intense, aggressive, driving, cinematic, big hits, trailer, promo, commercial, underscore, modern, contemporary, sporadic opener, intro, building, orchestral, big outro",
    "isPublished": true,
    "totalTracks": 0,
    "state": "available",
    "waveformData": [
        -127,
        127,
        -116,
        117,
        -123,
        "(…600+ datapoints per waveform…)",
        124,
        -69,
        67,
        -28,
        28
    ]
    "tagIds": [
        "5bbc9dd36d4c8b0014bf7a89",
        "5bbc9dd36d4c8b0014bf7ac2",
        "5bbc9dd26d4c8b0014bf7a7e"
    ],
    "groupIds": [
        "5b02d4700c052e0014c0e27c"
    ],
    "composerIds": [
        "5bbf4dfc65e261001304e2c8"
    ],
    "slug": "am12-46-death-mix",
    "originalFilename": "AM12_46_Kill 'Em All_Death",
    "orgSlug": "mylibrary",
    "isMain": false,
    "catalogueNumber": "AM12",
    "isrc": "QM-JGX-13-00173",
    "lyrics": "",
    "trackNumber": 46,
    "bpm": 0,
    "releaseId": "5bbf5d3165e261001304e885",
    "parentId": "5bbf6d8b65e261001305046e",
    "createdAt": "2018-10-11T15:34:36.585Z",
    "updatedAt": "2018-10-11T20:00:46.816Z",
    "__v": 0,
    "bitDepth": 16,
    "sampleRate": 44100,
    "duration": "00:02:28",
    "originalFormat": "aif",
    "originalAudio": "https://storage.googleapis.com/cadenzabox-prod-bucket/mylibrary/5bbf6d8c65e2610013050496_AM12_46_Kill 'Em All_Death.aif",
    "webAudio": "https://storage.googleapis.com/cadenzabox-prod-bucket/mylibrary/5bbf6d8c65e2610013050496_AM12_46_Kill 'Em All_Death_lo.mp3",
    "releaseTitleEn": "Deus Ex Machina",
    "releaseDate": "2010-10-18T00:00:00.000Z",
    "composers": [
        {
            "_id": "5bbf4dfc65e261001304e2c8",
            "slug": "kevin-rix-012345678",
            "firstName": "Kevin",
            "middleName": "",
            "lastName": "Rix"
        }
    ],
    "parent": {
        "_id": "5bbf6d8b65e261001305046e",
        "title": "Kill 'Em All",
        "description": "percussive action rock, thriller, dark, hybrid, orchestra, heavy metal guitars, intense, aggressive, driving, cinematic, big hits, trailer, promo, commercial, underscore, modern, contemporary, sporadic opener, intro, building, orchestral, big outro",
        "slug": "am12-45-main-mix",
        "isMain": true
    },
    "release": {
        "_id": "5bbf5d3165e261001304e885",
        "title": "Deus Ex Machina",
        "description": "The definition of Hybrid. Dark, heavy guitars, brutal drums and distorted synths lead the way for driving, urgent strings.",
        "isPublished": true,
        "totalTracks": 32,
        "state": "available",
        "tagIds": [
            "5c2e122d76b1b7001464115c"
        ],
        "groupIds": [
            "5b02d4700c052e0014c0e27c"
        ],
        "slug": "am12-deus-ex-machina",
        "orgSlug": "mylibrary",
        "originalPackshotFilename": "deusexmachina.jpg",
        "catalogueNumber": "AM12",
        "releaseDate": "2010-10-18T00:00:00.000Z",
        "createdAt": "2018-10-11T14:24:49.676Z",
        "updatedAt": "2018-12-04T18:12:53.708Z",
        "__v": 0,
        "packshot": {
            "original": "https://storage.googleapis.com/cadenzabox-prod-bucket/mylibrary/5bbf5d3165e261001304e885_deusexmachina.jpg",
            "300w": "https://storage.googleapis.com/cadenzabox-prod-bucket/mylibrary/5bbf5d3165e261001304e885_deusexmachina_300w.jpg",
            "750w": "https://storage.googleapis.com/cadenzabox-prod-bucket/mylibrary/5bbf5d3165e261001304e885_deusexmachina_750w.jpg"
        }
    },
    "groups": [
        null
    ],
    "tags": [
        {
            "_id": "5bbc9dd36d4c8b0014bf7a89",
            "name": "Action",
            "trackCount": 820,
            "orgSlug": "mylibrary",
            "parentId": "5bbc9dd26d4c8b0014bf7a74",
            "slug": "action",
            "createdAt": "2018-10-09T12:23:47.007Z",
            "updatedAt": "2019-01-03T17:28:17.803Z",
            "__v": 0,
            "suggest": true,
            "tags": []
        },
        {
            "_id": "5bbc9dd36d4c8b0014bf7ac2",
            "name": "Strings",
            "trackCount": 2218,
            "orgSlug": "mylibrary",
            "parentId": "5bbc9dd26d4c8b0014bf7a75",
            "slug": "strings",
            "createdAt": "2018-10-09T12:23:47.531Z",
            "updatedAt": "2019-01-03T17:28:17.798Z",
            "__v": 0,
            "suggest": true,
            "tags": []
        },
        {
            "_id": "5bbc9dd26d4c8b0014bf7a7e",
            "name": "Percussion",
            "trackCount": 2832,
            "orgSlug": "mylibrary",
            "parentId": "5bbc9dd26d4c8b0014bf7a75",
            "slug": "percussion",
            "createdAt": "2018-10-09T12:23:46.957Z",
            "updatedAt": "2019-01-03T17:28:17.798Z",
            "__v": 0,
            "suggest": true,
            "tags": []
        }
    ]
}

The tracks endpoint allows searching of tracks.

Track datapoints include:

parent tracks
parent release (and details, e.g. packshot)
tags
composers
web-audio preview for streaming
an array of audio levels (to produce a visual waveform)
...and lots more besides

Releases (albums)

# Releases (albums)
$ http GET "https://api.cadenzabox.com/releases" \
    "Origin:$origin"

# Individual release
$ http GET "https://api.cadenzabox.com/releases/$release_id" \
    "Origin:$origin"

Example response

{
    "_id": "5bbf5c4965e261001304e50a",
    "title": "Big, Big and Bigger",
    "description": "Blockbuster action, drama, raging rock and electronica, plus a selection of drum tracks rounds out this varied collection.",
    "isPublished": true,
    "totalTracks": 100,
    "state": "available",
    "tagIds": [],
    "groupIds": [
        "5b02d4700c052e0014c0e27c",
        "5c6bf987e122b1001454f62b"
    ],
    "slug": "am01-big-big-and-bigger",
    "orgSlug": "mylibrary",
    "originalPackshotFilename": "bigbigger.jpg",
    "catalogueNumber": "AM01",
    "releaseDate": "2001-07-31T00:00:00.000Z",
    "createdAt": "2018-10-11T14:20:57.890Z",
    "updatedAt": "2019-02-19T12:42:02.779Z",
    "__v": 0,
    "packshot": {
        "original": "https://storage.googleapis.com/cadenzabox-prod-bucket/mylibrary/5bbf5c4965e261001304e50a_bigbigger.jpg",
        "300w": "https://storage.googleapis.com/cadenzabox-prod-bucket/mylibrary/5bbf5c4965e261001304e50a_bigbigger_300w.jpg",
        "750w": "https://storage.googleapis.com/cadenzabox-prod-bucket/mylibrary/5bbf5c4965e261001304e50a_bigbigger_750w.jpg"
    }
}

The releases endpoint (referred to as the more user-friendly "albums" on client libraries) allows querying of releases.

Datapoints include:

title
description
how many (direct children) tracks are on the release
release date
packshot URLs
catalogue number

Playlists

# Playlists
$ http GET "https://api.cadenzabox.com/playlists" \
    "Origin:$origin"

# Individual playlist
$ http GET "https://api.cadenzabox.com/playlists/$playlist_id" \
    "Origin:$origin"

Example response (multiple playlists)

{
    "total": 4,
    "limit": 1,
    "skip": 0,
    "data": [
        {
            "_id": "5c51aea972b59d0014e82a5b",
            "isPublished": true,
            "tagIds": [],
            "trackIds": [],
            "title": "Triumph of the Human Spirit",
            "slug": "e684525034947b8cbefac3f4575a1a8f",
            "orgSlug": "mylibrary",
            "totalTracks": 0,
            "description": "The Academy presents this Gold Medal award to the season’s most magical, critically acclaimed, heartwarming event of the year.",
            "createdAt": "2015-09-08T21:26:40.000Z",
            "date": "2019-01-30T00:00:00.000Z",
            "updatedAt": "2019-02-12T12:32:10.459Z",
            "__v": 0,
            "packshot": {
                "original": "https://storage.googleapis.com/cadenzabox-qa-bucket/mylibrary/5c51aea972b59d0014e82a5b_playlist-triumph-of-the-human-spirit.jpg",
                "300w": "https://storage.googleapis.com/cadenzabox-qa-bucket/mylibrary/5c51aea972b59d0014e82a5b_playlist-triumph-of-the-human-spirit_300w.jpg",
                "750w": "https://storage.googleapis.com/cadenzabox-qa-bucket/mylibrary/5c51aea972b59d0014e82a5b_playlist-triumph-of-the-human-spirit_750w.jpg"
            }
        }
    ]
}

The playlists endpoint allows querying of playlists.

Datapoints include:

title
description
how many (direct children) tracks are on the playlists
packshot URLs

Projects

# Projects list (as authenticated for a specific user)
$ http GET "https://api.cadenzabox.com/projects" \
    "Authorization:$authorization" \
    "Origin:$origin"

# Individual project
$ http GET "https://api.cadenzabox.com/projects/$project_id" \
    "Origin:$origin"

Example response (individual project)

{
    "_id": "5c12d1973819ec0013473a15",
    "title": "TestProject777",
    "isFavourite": false,
    "trackIds": [
        "5be32020a0e4d100136819bf",
        "5be32020a0e4d100136819c4"
    ],
    "ownerId": "5b02d4ea0c052e0014c0e27e",
    "orgSlug": "mylibrary",
    "slug": "test-project777",
    "createdAt": "2018-12-13T21:39:35.715Z",
    "updatedAt": "2018-12-13T21:44:52.280Z",
    "__v": 0
}

Projects are user generated collections of tracks. These are ideally suited to creating pitches, or saving a selection of tracks potentially useful on a specific production.

Datapoints include

title
description
how many (direct children) tracks are on the project
track ids of the child tracks

Access

Authenticated users can create new projects. A new project is owned by the user that created it. Users can also list, update and delete their own projects only. A user cannot list, update or delete anyone else’s project, however, any project can be read, regardless of authentication, if the $project_id is known.

Why are projects accessible?

Individual projects are always accessible, regardless of authentication. This is to allow a shared project to be accessible by the sharee, who needn’t be logged in, or indeed even have a user account. Regarding the privacy of (as yet) “unshared” projects, we presume that guessing a valid identifier is pseudo-impossible as guessing a valid hex value is a 1 in >7×10²⁸ chance.