API Reference

The White Label API serves your collections, mixtapes, tracks, and more through a simple API interface.

White Label resources are accessed and manipulated in a similar manner. A list of the latest resource is usually available through /{resource}/, a filtered list through /{resource}/?filter=filter, and a single specific resource through /{resource}/{id-slug}/.

Unless otherwise specified, the base URL for API endpoints is:

https://beta.whitelabel.cool/api

Remember: If you are developing an app from scratch, you will need a SoundCloud developer token to stream audio.

A note on Imgix URLs

Imgix is a handy service that accepts a single, high resolution image, then renders altered versions of the image based on URL query parameters. For Noon Pacific, this means we can load the smallest version of an image necessary without compromising quality on screen. For example, the WL API might return the following cover art URL.

https://production-whitelabel.imgix.net/media/mixtapes/199.jpg

To render the image on an iPhone 5 at 2X resolution, we could add the following query parameters.

https://production-whitelabel.imgix.net/media/mixtapes/199.jpg?w=300&h=300&dpr=2

Learn more about how you can manipulate White Label images using the Imgix API here.

A note on ordering

Lists can be ordered according to certain properties. You can specify a single property, or chain together multiple properties separated by a comma. For example, the following URL will return a set of mixtapes ordered by title, then, if two or more titles match, ordered by release date.

https://beta.whitelabel.cool/api/mixtapes/?ordering=title,release

You may also specify reverse orderings by prefixing the field name with '-', like so.

https://beta.whitelabel.cool/api/mixtapes/?ordering=-title

A note on shuffling

Object lists can be shuffled to provide a variable listening experience for your listeners. Specify the ordering parameter as shuffle to return a randomized list.

https://beta.whitelabel.cool/api/mixtapes/?ordering=shuffle

To work with a paginated list of shuffled results, provide a seed for your shuffle. A seed is a key of letters and numbers from which a specific shuffle set is extrapolated. By maintaining a single seed for you shuffle session, your paginated results will remain consistent.

https://beta.whitelabel.cool/api/mixtapes/?ordering=shuffle&seed=n128hSJ4AS&page=3

If no seed is provided, a seed will be automatically generated for you. The seed is always available for reference at the top of your shuffled response.

{
  "count": 218,
  "next": "https://beta.whitelabel.cool/api/mixtapes/?ordering=shuffle&page=4&seed=n128hSJ4AS",
  "previous": "https://beta.whitelabel.cool/api/mixtapes/?ordering=shuffle&page=2&seed=n128hSJ4AS",
  "seed": "n128hSJ4AS",
  "results": [
    ...
  ]
}

/label/

Full URI: https://beta.whitelabel.cool/api/label/

HTTP Method: GET

Retrieve your label object.

Properties

Name Type Description
id Integer An ID number that uniquely identifies your label.
name String The name of your label.
slug String A string that uniquely identifies your label.
icon URL The Imgix URL of the icon for your label.
service Object A Service object, specifying the id, name, slug and external URL of the music service your label curates from.

Example

curl --request GET \
--header 'Accept: application/json; version=1.0' \
--header 'Client: YOUR_CLIENT_ID' \
--url 'https://beta.whitelabel.cool/api/label/'
{
  "id": 1,
  "name": "Noon Pacific",
  "slug": "noon-pacific",
  "icon": "https://production-whitelabel.imgix.net/media/icons/noon-pacific.png",
  "service": {
    "id": 1,
    "name": "SoundCloud",
    "slug": "soundcloud",
    "external_url": "https://soundcloud.com"
  }
}

/collections/

Full URI: https://beta.whitelabel.cool/api/collections/

HTTP Method: GET

Retrieve a list of collections associated with your label. By default, all collections are returned, ordered by the created property. This endpoint is paginated every 20 records, so collections are nested in the results array.

Properties

Name Type Description
id Integer An ID number that uniquely identifies this collection.
title String The title of the collection.
slug String A string that uniquely identifies this collection.
description String A Markdown description of the collection.
artwork_url URL The Imgix URL of the artwork image for this collection.
artwork_credit String The creator of the artwork image.
artwork_credit_url URL The URL of the portfolio of the creator of the artwork image for this collection.
created Date/Time The date and time the collection was created (and thus released), in UTC format.
mixtape_count Integer The total number of mixtapes within this collection.

Filters

Parameter Type Description
search String Search collection titles for a matching substring.
ordering String Order by id, title, created, and/or shuffle.

Example

curl --request GET \
--header 'Accept: application/json; version=1.0' \
--header 'Client: YOUR_CLIENT_ID' \
--url 'https://beta.whitelabel.cool/api/collections/?ordering=title'
{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 21,
      "title": "Special Editions",
      "slug": "special-editions",
      "description": "For the special snowflakes",
      "artwork_url": null,
      "artwork_credit": "",
      "artwork_credit_url": "",
      "created": "2016-02-29T22:40:15.453000Z",
      "mixtape_count": 9,
    },
    {
      "id": 18,
      "title": "Weekly",
      "slug": "weekly",
      "description": "Weekly mixtapes delivered every Monday at noon, Pacific time.",
      "artwork_url": "https://production-whitelabel.imgix.net/media/collections/NP-01.png",
      "artwork_credit": "",
      "artwork_credit_url": "",
      "created": "2016-02-29T22:40:34.965000Z",
      "mixtape_count": 188,
    }
    ...
  ]
}

/collections/{collection}/

Full URI: https://beta.whitelabel.cool/api/collections/{collection}/

HTTP Method: GET

Retrieve a single collection object, where {collection} is either the ID or slug of the specified collection.

Example

curl --request GET \
--header 'Accept: application/json; version=1.0' \
--header 'Client: YOUR_CLIENT_ID' \
--url 'https://beta.whitelabel.cool/api/collections/weekly/'
{
  "id": 18,
  "title": "Weekly",
  "slug": "weekly",
  "description": "Weekly mixtapes delivered every Monday at noon, Pacific time.",
  "artwork_url": "https://production-whitelabel.imgix.net/media/collections/NP-01.png",
  "artwork_credit": "Noon Pacific LLC",
  "artwork_credit_url": "",
  "created": "2016-02-29T22:40:34.965000Z",
  "mixtape_count": 188,
}

/mixtapes/

Full URI: https://beta.whitelabel.cool/api/mixtapes/

HTTP Method: GET

Retrieve a list of released mixtapes associated with your label. By default, all released mixtapes are returned, ordered by parent collection then release. This endpoint is paginated every 20 records, so mixtapes are nested in the results array.

Properties

Name Type Description
id Integer An ID number that uniquely identifies this mixtape.
title String The title of the mixtape.
slug String A string that uniquely identifies this mixtape.
description String A Markdown description of the mixtape.
artwork_url URL The Imgix URL to retrieve the artwork image for this mixtape.
artwork_credit String The creator of the artwork image.
artwork_credit_url URL The URL of the portfolio of the creator of the artwork image for this mixtape.
sponsor String The sponsor of this mixtape.
sponsor_url URL The URL of the sponsor of this mixtape.
product String The product associated with this mixtape.
product_url URL The URL of the product associated with this mixtape.
release Date/Time The date and time the mixtape is scheduled for release, in UTC format.
track_count Integer The total number of tracks within this mixtape.
created Date/Time The date and time the mixtape was created, in UTC format.
collection Integer The ID of the parent collection.

Filters

Parameter Type Description
search String Search mixtape titles for a matching substring.
ordering String Order by id, title, release, collection, and/or shuffle.
min_release Date/Time The minimum date and time a mixtape was released, in UTC format.
max_release Date/Time The maximum date and time a mixtape was released, in UTC format.
collection Integer or String Retrieve mixtapes belonging to a collection, specified by the parent collection's ID or slug.

Example

curl --request GET \
--header 'Accept: application/json; version=1.0' \
--header 'Client: YOUR_CLIENT_ID' \
--url 'https://beta.whitelabel.cool/api/mixtapes/?collection=weekly'
{
  "count": 188,
  "next": "https://beta.whitelabel.cool/api/mixtapes/?page=2",
  "previous": null,
  "results": [
    {
      "id": 252,
      "title": "NOON // 187",
      "slug": "noon-187",
      "description": "",
      "artwork_url": "https://production-whitelabel.imgix.net/media/mixtapes/cover_large_252.jpg",
      "artwork_credit": "Kyle Kuiper",
      "artwork_credit_url": "http://www.instagram.com/kdkuiper",
      "sponsor": "The Lot Radio",
      "sponsor_url": "http://www.thelotradio.com/",
      "product": "",
      "product_url": "",
      "release": "2016-04-18T19:00:00Z",
      "track_count": 10,
      "created": "2016-04-13T00:22:39.451000Z",
      "collection": 1
    },
    {
      "id": 251,
      "title": "NOON // 186",
      "slug": "noon-186",
      "description": "",
      "artwork_url": "https://production-whitelabel.imgix.net/media/mixtapes/cover_large_251.jpg",
      "artwork_credit": "Woody Gooch",
      "artwork_credit_url": "https://www.instagram.com/woodygphoto/",
      "sponsor": "Coachella Guide 2016",
      "sponsor_url": "http://noonpacific.com/coachella-guide-2016/",
      "product": "",
      "product_url": "",
      "release": "2016-04-11T19:00:00Z",
      "track_count": 10,
      "created": "2016-04-08T16:17:40.508000Z",
      "collection": 1
    },
    ...
  ]
}

/mixtapes/{mixtape}/

Full URI: https://beta.whitelabel.cool/api/mixtapes/{mixtape}/

HTTP Method: GET

Retrieve a single mixtape object, where {mixtape} is either the ID or slug of the specified mixtape.

Example

curl --request GET \
--header 'Accept: application/json; version=1.0' \
--header 'Client: YOUR_CLIENT_ID' \
--url 'https://beta.whitelabel.cool/api/mixtapes/noon-186/'
{
  "id": 251,
  "title": "NOON // 186",
  "slug": "noon-186",
  "description": "",
  "artwork_url": "https://production-whitelabel.imgix.net/media/mixtapes/cover_large_251.jpg",
  "artwork_credit": "Woody Gooch",
  "artwork_credit_url": "https://www.instagram.com/woodygphoto/",
  "sponsor": "Coachella Guide 2016",
  "sponsor_url": "http://noonpacific.com/coachella-guide-2016/",
  "product": "",
  "product_url": "",
  "release": "2016-04-11T19:00:00Z",
  "track_count": 10,
  "created": "2016-04-08T16:17:40.508000Z",
  "collection": 1
}

/mixtapes/latest/

Full URI: https://beta.whitelabel.cool/api/mixtapes/latest/

HTTP Method: GET

Retrieve the most recently published mixtape object.


/tracks/

Full URI: https://beta.whitelabel.cool/api/tracks/

HTTP Method: GET

Retrieve a list of released tracks associated with your label. By default, all released tracks are returned, ordered by parent mixtape then order. This endpoint is paginated every 20 records, so tracks are nested in the results array.

Properties

Name Type Description
id Integer An ID number that uniquely identifies this track.
mixtape Integer The ID of the parent mixtape.
title String The title of the track.
artist String The artist of the track.
slug String A string that uniquely identifies this track.
streamable Boolean Denotes if the track can be streamed. Note: This property is for UI rendering only. All streaming clients should check each track for playability.
duration Integer The duration of this track (in milliseconds).
external_id Integer The unique identifier for this track on an external service (like SoundCloud).
stream_url URL The link to stream this track's audio on an external service (like SoundCloud).
permalink_url URL The link to the web page of this track on an external service (like SoundCloud).
artwork_url URL The link to retrieve the artwork image for this track on an external service (like SoundCloud).
purchase_url URL The link to buy this track.
download_url URL The link to download this track.
ticket_url URL The link to purchase a ticket associated this track.
play_count Integer The total number of times this track was played.
order Integer The order index of the track within the parent mixtape.

Filters

Parameter Type Description
search String Search track titles and artists for a matching substring.
ordering String Order by id, title, artist, mixtape, streamable, duration, and/or shuffle
streamable bool Specify "True" or "False" to retrieve a list of streamable tracks.
mixtape Integer or String Retrieve tracks belonging to a mixtape, specified by the parent mixtapes's ID or slug.

Example

curl --request GET \
--header 'Accept: application/json; version=1.0' \
--header 'Client: YOUR_CLIENT_ID' \
--url 'https://beta.whitelabel.cool/api/tracks/?mixtape=noon-186'
{
  "count": 10,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 2731,
      "mixtape": 251,
      "title": "Episode",
      "artist": "Gallant",
      "slug": "gallant-episode",
      "streamable": true,
      "duration": 276976,
      "external_id": 257628231,
      "stream_url": "https://api.soundcloud.com/tracks/257628231/stream",
      "permalink_url": "http://soundcloud.com/gallant/episode",
      "purchase_url": "",
      "download_url": "",
      "artwork_url": "",
      "play_count": 1730,
      "order": 1
    },
    {
      "id": 2750,
      "mixtape": 251,
      "title": "The Mission",
      "artist": "LESSI",
      "slug": "lessi-the-mission",
      "streamable": true,
      "duration": 354958,
      "external_id": 263722469,
      "stream_url": "https://api.soundcloud.com/tracks/263722469/stream",
      "permalink_url": "http://soundcloud.com/deepsounds/lessi-the-mission",
      "purchase_url": "http://dl.aia.ag/lessi-the-mission",
      "download_url": "https://www.amazon.com/Mission-Single-LESSI/dp/B01F31K8MK",
      "artwork_url": "https://i1.sndcdn.com/artworks-000162459295-d5pw8o-large.jpg",
      "play_count": 948,
      "order": 2
    },
    ...
  ]
}

/tracks/{track}/

Full URI: https://beta.whitelabel.cool/api/tracks/{track}/

HTTP Method: GET

Retrieve a single track object, where {track} is either the ID or slug of the specified track.

Example

curl --request GET \
--header 'Accept: application/json; version=1.0' \
--header 'Client: YOUR_CLIENT_ID' \
--url 'https://beta.whitelabel.cool/api/tracks/lessi-the-mission/'
{
  "id": 2750,
  "mixtape": 251,
  "title": "The Mission",
  "artist": "LESSI",
  "slug": "lessi-the-mission",
  "streamable": true,
  "duration": 354958,
  "external_id": 263722469,
  "stream_url": "https://api.soundcloud.com/tracks/263722469/stream",
  "permalink_url": "http://soundcloud.com/deepsounds/lessi-the-mission",
  "purchase_url": "http://dl.aia.ag/lessi-the-mission",
  "download_url": "https://www.amazon.com/Mission-Single-LESSI/dp/B01F31K8MK",
  "artwork_url": "https://i1.sndcdn.com/artworks-000162459295-d5pw8o-large.jpg",
  "play_count": 948,
  "order": 2
}

/events/plays/{track}/

Full URI: https://beta.whitelabel.cool/api/tracks/{track}/

HTTP Method: POST

Log a playback event, where {track} is either the ID or slug of the specified track. To accurately measure playback in your apps, we recommend you call this endpoint 5 seconds after the start of the track's audio.

Example

curl --request POST \
--header 'Accept: application/json; version=1.0' \
--header 'Client: YOUR_CLIENT_ID' \
--url 'https://beta.whitelabel.cool/api/events/plays/lessi-the-mission/' \
--include
HTTP/1.1 201 Created
Allow: POST, OPTIONS
Content-Type: text/plain; charset=UTF-8
Date: Sat, 16 Jul 2016 14:50:20 GMT
Server: Apache/2.4.18 (Amazon) mod_wsgi/3.5 Python/2.7.10
Vary: Accept,Authorization,Host
X-Frame-Options: SAMEORIGIN
Content-Length: 0
Connection: keep-alive