AudioBox API Platform Documentation (Release Notes)

AudioBox let developers access to API in order to build any kind of modern applications, libraries and integrations on top of the platform.

AudioBox exposes basic and special API endpoints aimed at fast iteration of code and easiness.

All the HTTP/HTTPS must be performed using the JSON data format and content type.

Authentication

The platform supports different authentication schemes, such as:

  • HTTP Basic Auth
  • Auth Token appended in a parameter auth_token during a request (ex. /api/v1/user.json?auth_token=xxx) or injected as a request HTTP header named X-AUTH-TOKEN
  • OAuth2 (preferred)

We have different authentication schemes to support as many platforms and operating systems as possible, from a Bash script to a iOS app.
Please keep in mind user's credentials security when working with AudioBox. Use encryption, HTTPS and make sure to follow the best security practice for the platform you are writing software for.

OAuth2

AudioBox supports different OAuth2 grant types:

  • Resource Owner Password Credentials Grant Type
  • Client Credentials Grant Type
  • Authorization Code Grant Type
  • Implicit Grant Type
  • Refresh Token Grant Type

Cookies and Refresh tokens

When attempting to issue a request to the /oauth2 endpoints, make sure your HTTP requests are cookie-less.

Endpoints

  • Base API URL: https://audiobox.fm/api/v1
  • Authorize path: https://audiobox.fm/oauth2/authorize
  • Token path: https://audiobox.fm/oauth2/token

Create your Application

To create OAuth2 applications you must be a registered and signed in user, then go to this page.

Offline strategies

AudioBox is not meant to act as a bidirectional platform as one of our goals is to to save disk space, however it may be desiderable to store content on user's devices for caching purposes.
To leverage this concept we introduced a special "Offline" playlist: the user can select any media file (beside YouTube ones) and drag them onto this playlist for offline usage. The Offline playlist is no different from a custom playlist, with the exception that adding YouTube media files will have no effect.

Notes:

  • The content of the offline playlist is always available as it does not depend on the state of the user authentication toward external services or the actual subscription.
  • The Offline playlist will return the metadata for the tracks as any other playlist that the user wish to be available offline. However when asking the tracks via the proper download endpoint it may result in error because of the user's subscription state or invalid authentication tokens.
  • User's files stored in AudioBox Cloud will be always available given a valid user and subscription as they do not depend on external services.
  • User's files stored in AudioBox Desktop are not in a remote cloud, but on the user's computer, either via an iTunes playlist or through Folder Scan. What matters however is that we will bridge downloads of files stored AudioBox Desktop, but their availability is strictly tied to a running and configured desktop application.

Consumer API Documentation

The AudioBox Platform has different types of Accounts, this section describes the interfaces for regular Users.
A User can interact with his own files in different ways, depending on the remote storages in play.
However our platform is built with homogeneity in mind and therefore you will end up calling the same endpoints for different, powerful actions.

Note: click the near each endpoint to show API details.

Account API

GET
/api/v1/user.json

Returns informations about the currently logged in user. Supports ETag caching.

For the most part the returned attributes are straighforward, such as media_files_count, however there are special attributes to explain:

auth_token:

The current authentication token for the user. This attribute can change and might be rotated at any time.

permissions: {...}

A user can subscribe and manage multiple remote storage services. This hash defines the boolean permissions the user has access to, depending on subscription state if it's a paid feature. In case the User has been created through a Partner it will inherit permissions depending on the Partner requested features.
Such attributes are automatically set by the system and cannot be changed manually.

oauth_tokens: {...}

For each of the external services the boolean value indicates if we have stored a OAuth token for the user.
Such attributes are automatically set by the system and cannot be changed manually.

stats: {...}

Bytes integer values showing the storage used for each supported storage service and the amount of data that has been streamed.

subscription_state:

String identifying the paid subscription states for this user. Some features cannot be accessed if the subscription is not valid. We suggest to not use logic in your own application against this attribute, but rather query the permissions: {} data to have more fine-grained control over the available actions.
Possible values are: active, trialing, past_due, canceled and unpaid.

plan:

The plan name the user is subscribed to, if any.

comet_channel:

The unique push engine channel for this user. AudioBox employ push notifications, by making the application subscribe to this channel name it will be able to receive actions to perform in the user interface.
Using push messages is a great way to keep all the applications in sync when an action is performed, such as media add. Further documentation on how to connect to the push server will be provided soon.

preferences: {...}

General preferences of the user, mostly used in the Cloud Web Player.

Cloud Drives and Playlists API

Playlists are the main containers for Media Files and are represented in the system by an unique token.
Internally a Cloud Drive is treated as a Playlist.
There are different types of playlists and each one can represent a particular media storage service, here's a rundown:

LocalPlaylist

Contains AudioBox Desktop media files. AudioBox Desktop is an application that is able to stream media files directly from the User's pc, without uploading an entire collection first.
During normal desktop usage and syncing this playlist will be filled with metadata of files found on the user's filesystem in the folder he specified. This playlist is not treated differently, except that media files actions are limited, such as destroy, since it is automatically managed.

CloudPlaylist

Contains AudioBox Cloud media files. AudioBox Cloud is the official AudioBox Cloud Media Storage offering and it's available space is unlimited.
This playlist can be accessed only when a valid subscription is in place, so in order to perform actions against it make sure that the permissions: cloud is true in the /api/v1/user.json call.

DropboxPlaylist, SkydrivePlaylist, BoxPlaylist, GdrivePlaylist, YouTubePlaylist, SoundcloudPlaylist, UbuntuPlaylist

Contains media files synced from the relative remote storage. Accessible when a valid subscription exists, whereas applicable, and a proper service authentication is stored in database. The link between an AudioBox account and the remote service is called an AudioMash.

CustomPlaylist

User-created playlist that contains media files assigned by the user.

SmartPlaylist

User-created playlist that contains media files that corresponds to rules defined by the user. Updates automatically on demand.

OfflinePlaylist

System-created playlist that contains media files the user would like to store on client.

Each playlist supports a set of attributes:

token:
identifier used to perform actions on a playlist, usually part of the URL.
offline (deprecated):
boolean identifying if this playlist is set for syncing content for offline usage, this is a user's preference. Any playlist can be set for offline usage. YouTube has no effect.
embeddable:
boolean identifying if this playlist can be embedded on an external website. For future use.
visible:
boolean identifying if this playlist should be hidden from the user interface.
syncable:
boolean identifying if this playlist supports syncing with remote content, usually valid for external storage services.
system_name:
a code friendly name identifying playlist's type.
position:
integer identifying the order of which playlists should be shown, this is a user's preference. The most important playlists has this attribute unchangeable.

GET
/api/v1/playlists.json

Returns a list of all the playlist in the user's account.
Please note that this step does not fires the job to recompile a SmartPlaylist.

Returns:

HTTP Status 200:
Success.
HTTP Status 304:
When asked with a correct If-None-Match Etag header. This call does not support If-Modified-Since.

GET
/api/v1/playlists/:token.json

Returns up to date informations about a single playlist identified by token.
Supports Etag caching. Trigger Smart Playlist compilation if the requested playlist is a SmartPlaylist.

POST
/api/v1/playlists.json

Automatically creates a new CustomPlaylist or SmartPlaylist depending on the input parameters.

The user can create a CustomPlaylist by sending playlist[name].

The user can create a SmartPlaylist by sending playlist[name] and playlist[search_params]. Currently the search_params hash construction is complex enough and therefore it's restricted to the Cloud Web Player, we'll open up the possibility for developers to create them as well.

PUT
/api/v1/playlists/:token.json

Handle the update of a custom or smart playlist.

As a rule of thumb you can have one uniquely named playlist for each type. SmartPlaylist's +search_params+ can be set only on creation and thus cannot be changed, in this action.
SmartPlaylist are not tweakable in their search_params due to the complexity of their construct. Since SmartPlaylist are compiled on demand, just destroy the old and create a new one.

Returns:

HTTP Status 204:
Success.
HTTP Status 404:
Playlist not found or immutable (not smart or custom).
HTTP Status 422:
Validation errors, please inspect the body.

DELETE
/api/v1/playlists/:token.json

Permanently destroy a playlist.

Only Custom and Smart playlists can be destroyed.

PUT
/api/v1/playlists/:token/offline.json (deprecated in 2.3.0)

Toggle offline mode for custom and smart playlists.

Has no effect since 2.3.0. Please add media files in the dedicated Offline playlist.

PUT
/api/v1/playlists/:token/visible.json

Toggle visibility mode for all playlists.

By toggling the visibility attribute clients should avoid to render the playlist marked with visible: false or grey them out. Non visible playlists retains their functionality, they just should be hidden in views.

PUT
/api/v1/playlists/:token/sync.json

Begin content sync with the remote platform. Supported only by syncable: true playlists.

Calling this endpoint will initiate a job that will synchronize data with the remote storage, such as Dropbox, SkyDrive and others. Playlists supporting official storage such as AudioBox Cloud or AudioBox Desktop does not require syncing.

Returns:

HTTP Status 204:
Success.
HTTP Status 402:
Action requires a valid subscription.
HTTP Status 403:
Playlist requires a valid account link to the remote service.
HTTP Status 404:
Playlist not found.
HTTP Status 422:
Playlist not suitable for syncing.

PUT
/api/v1/playlists/sync_all.json

Begin sync with remote content in all playlists that supports it.

Calling this endpoint will initiate a job that will synchronize data with the remote storage of all the supported playlists.

Returns:

HTTP Status 204:
Success.

Media Files API

Media Files are the most important entity in the platform, has many properties, are editable, deletable and streamable.
Not every media container is supported by AudioBox, you can find this informations in the user.json API call by looking user.accepted_extensions and user.accepted_formats.

Uploads

Media Files uploaded into AudioBox Cloud will use storage space that will count toward the monthly bill of the User. Please always check the permissions.cloud value prior to attempt an upload since a subscription might no be in good standing.

Streaming

Developers can request to stream a file in any moment.

Attributes

type:
string, readonly. Can be either 'AudioFile' or 'VideoFile'
token:
string, readonly. Identify uniquely this Media File in the system
artist:
string, readwrite. Artist name, automatically set depending on the Cloud Drive in use, if not set.
album:
string, readwrite. Album name, automatically set depending on the Cloud Drive in use if not set.
genre:
string, readwrite. Genre name, automatically set depending on the Cloud Drive in use if not set.
release_year:
integer, readwrite. Four integers, represents the year when the Media File has been released.
title:
string, readwrite. The title of this Media File.
album_artist:
string, readwrite. Album Artist name. Useful to differentiate between compilations.
composer:
string, readwrite. Composer name.
comment:
string, readwrite. Custom comment.
len_str:
string, readonly. Formatted as "3:04" to ease display in views. Represents the duration of the media file.
len_int:
integer, readonly. Represents the duration in seconds of the media file.
position:
integer, readwrite. Represents the position this Media File occupy in a collection/album (track's number).
filename:
string, readonly. File name indicating where the file has been stored on our systems.
loved:
boolean, readwrite. Indicates if this Media File is 'loved' by its owner or not. Default is false.
disc_number:
integer, readwrite. Represents the number of the disc in a multi collection set.
mime:
string, readonly. Formatted such as "audio/mpeg", represents the recognized mime type for this file. This value can help some client to better recognize the type of file to be streamed.
remote_path:
string, readonly. Used along with some Cloud Drives to help the platform identifying where this file is stored for retrieval.
source:
string, readonly. Represents where this Media File comes from. Possible values are: 'cloud', 'local', 'dropbox', 'skydrive', 'box', 'gdrive', 'youtube', 'soundcloud'.
share_token:
string, readonly. Shared token across multiple Media Files with the same artist/album combo that builds up a Share URL, such as: http://audiobox.fm/share/cfa4b55e1736415b491147f041b95392.
artwork:
string, readwrite. Represents the path for the Artwork of a Media File on the HTTP(S) CDN m.audiobox.fm. 256x256. 1.5MB Max. PNG/JPEG/GIF.
size:
integer, readonly. Physical size of the Media File, in bytes.
hash:
string, readonly. MD5 Hash of the Media File.
video_bitrate:
string, readonly. Indicates the bitrate in case of VideoFile.
video_codec:
string, readonly. Indicates the codec in case of VideoFile.
video_resolution:
string, readonly. Indicates the resolution in case of VideoFile.
video_fps:
string, readonly. Indicates the frame per second in case of VideoFile.
video_aspect:
string, readonly. Indicates the aspect ratio in case of VideoFile.
video_container:
string, readonly. Indicates the container in case of VideoFile.
audio_bitrate:
string, readonly. Indicates the bitrate in case of AudioFile or the first audio track in a VideoFile.
audio_codec:
string, readonly. Indicates the codec in case of AudioFile or the first audio track in a VideoFile.
audio_sample_rate:
string, readonly. Indicates the sample rate in case of AudioFile or the first audio track in a VideoFile.

Uploading

POST
/api/v1/upload

Upload media files in AudioBox Cloud.

If the subscription is not valid the upload server will refuse the uploads with a 402 HTTP status (payment required).
If a media file already exists on AudioBox Cloud the upload server will return a 409 HTTP status (conflict).
Other errors might include 422, 503 or 500 with additional informations in the response's body. The application should ensure to accept those errors and retry accordingly after few minutes.
On successful upload the server returns a 202 with additional informations in the response's body, including the token assigned to a single media file.
If you are uploading multiple media files in a single pass this endpoint will return a JSON array in the response's body.
Files uploaded through this endpoint will go directly into the CloudPlaylist.

cURL example:

curl -v -k -F files[]=@myFile.mp3 -H 'x-auth-token:MY_AUTH_TOKEN' https://audiobox.fm/api/v1/upload

OPTIONS
/api/v1/upload

Useful for web uploaders not on the same audiobox.fm domain.

Streaming

GET
/api/v1/stream/:token

Begin streaming of the file.

The requested file will be streamed to the requesting client.

The client should be ready to follow all redirects, as there may be multiple depending on the source drive.

Downloading

GET
/api/v1/download/:token

Begin downloading of the file.

The requested file will be downloaded to the requesting client.

The client should be ready to follow all redirects, as there may be multiple depending on the source drive.

Whereas possibile we will send the Content-Disposition header along with the original file name.

Listings and Grouping

GET
/api/v1/media_files/:token.json

Shows the full informations of a media file.

Returns:

HTTP Status 200:
Success, files shown.
HTTP Status 404:
File not found.

GET
/api/v1/playlists/:playlist_token/media_files.json?set=type,token,artist,genre,title,loved,share_token,release_year,len_str,[...]&since=

Returns media files linked to the specified playlist token along with primary informations.

This does not return all the attributes for a MediaFile, instead it returns an optimized JSON for fast view-level rendering and parsing purposes. Full details about a particular MediaFile can be obtained by calling the dedicated show endpoint.

Supports a comma separated 'set' parameter which indicates which attributes to render, like 'type,token' so a developer can just ask the needed attributes.

Supports a datetime 'since' parameter that filters the collection and returns records modified since the specified date.

Remote and third party Cloud Storage services' content can be accessed through this endpoint, however an error will be returned if the user has no valid authentication informations stored towards the service in question or has an invalid subscription. For example if the user tries to access the Dropbox playlist but he has not the related account linked a 403 will be returned, along with the subscription status. Valid subscription statuses are active and trialing.

This will also return a 403 if the AudioBox Desktop (local) playlist has been requested but the software is not running.

Optional parameters:

set
Hand picked comma separated attributes, such as 'type,token'
since
UTC Datetime (preferable in UNIX format) that returns only records modified since the specified date.

Returns:

HTTP Status 200:
Success.
HTTP Status 403:
User is not enabled to view this playlist due to bad subscription state, missing AudioMash link or required software not running.
HTTP Status 404:
Playlist does not exists.

GET
/api/v1/playlists/:token/media_files/albums.json

Returns grouped Albums data.

Also includes the same media file entities in other collection views, sorted by the media files' position attribute.

Returns:

HTTP Status 200:
Success.
HTTP Status 403:
User is not enabled to view this playlist due to bad subscription state or missing AudioMash link.
HTTP Status 404:
Playlist does not exists.

GET
/api/v1/playlists/:token/media_files/genres.json

Returns grouped Genre data.

Also includes the same media file entities in other collection views, sorted by the media files' artist, album and position attributes.

Returns:

HTTP Status 200:
Success.
HTTP Status 403:
User is not enabled to view this playlist due to bad subscription state or missing AudioMash link.
HTTP Status 404:
Playlist does not exists.

GET
/api/v1/playlists/:token/media_files/artists.json

Returns grouped Artist data.

Also includes the same media file entities in other collection views, sorted by the media files' album and position attribute.

Returns:

HTTP Status 200:
Success.
HTTP Status 403:
User is not enabled to view this playlist due to bad subscription state or missing AudioMash link.
HTTP Status 404:
Playlist does not exists.

GET
/api/v1/playlists/:playlist_token/media_files/fingerprints.json

Returns known file fingerprints for this playlist. Available only for local and cloud playlist tokens.

This endpoint will return all MD5 fingerprints of the media files on this playlist. Useful to know what has already been uploaded.
The 'local' source attribute value represents files received from AudioBox Desktop, the 'cloud' source indicates media files stored on AudioBox Cloud.
Supports ETAG caching.

Returns:

HTTP Status 200:
Success.
HTTP Status 304:
Success.

File Operations

POST
/api/v1/playlists/:playlist_token/media_files/add.json?tokens[]=

Add Media Files to a CustomPlaylist.

Shallow action that requires an array of media files tokens to be added to this custom playlist via the 'tokens' paramer. Media files can be added manually only to custom playlists.

Required parameters:

tokens
Array of Media Files tokens to be added.

Returns:

HTTP Status 204:
Success, files added.
HTTP Status 404:
Playlist not found or not of type CustomPlaylist.

DELETE
/api/v1/playlists/:playlist_token/media_files/remove.json?tokens[]=

Remove Media Files from a CustomPlaylist.

Shallow action that requires an array of media files tokens to be removed from this playlist via the 'tokens' parameter.
Allow removing media files from a custom playlist. Only custom playlist tokens are allowed, being the only ones for which content can be modified. Smart playlists and remote cloud drivers are automatic.
The tokens array will be processed and duplicates removed. The system will not remove media files not present in the destination playlist.

Required parameters:

tokens
Array of Media Files tokens to be removed.

Returns:

HTTP Status 204:
Success, files removed.
HTTP Status 404:
Playlist not found or not of type CustomPlaylist.

PUT
/api/v1/media_files/:token.json

Handle a single media file update.

Required parameters:

media_file[attr1]
Attribute and value, such as media_file[title]=Immortal

Returns:

HTTP Status 204:
Success, files updated.
HTTP Status 404:
File not found.
HTTP Status 422:
Validation errors, please inspect the response body.

PUT
/api/v1/media_files/multiupdate.json?tokens[]=

Updated multiple media files with the data provided.

Permanently update the record with the data provided. Accepts a 'tokens' parameter array indicating all the tokens that needs to be updated.

Due to potential binary attachments (artworks) this call will take into account 100 media files tokens maximum.

For each media file updated succesfully a push message media_update is sent to channel subscribers with the new informations.

Returns the chosen media files.

Required parameters:

tokens
Array of Media Files tokens.
media_file[attr1]
Attribute and value, such as media_file[title]=Immortal

Returns:

HTTP Status 204:
Success, files updated.

DELETE
/api/v1/media_files/:token.json

Handle a single media file destruction synchronously.

If you need to permanently destroy more than one single media file in one sweep use multidestroy.

Do not attempt to call this endpoint for single tracks the user selected to destroy.

This will remove the media file from our database. If the media file is stored on AudioBox Cloud it will be physically removed as well. If the media file is stored on a remote storage solution like AudioBox Desktop, Dropbox, SkyDrive, etc. it will not be harmed unless management mode is enabled.

Returns:

HTTP Status 204:
Success, file deleted.
HTTP Status 404:
File not found.

DELETE
/api/v1/media_files/multidestroy.json?tokens[]=

Handle multiple media files destruction. This call is async.

Accepts a params[:tokens] array indicating all the tokens that needs to be forever deleted. If the user enabled management mode and this is a remote file, say YouTube, it will be deleted as well, so always show the user a confirmation prompt about what he's doing.

Required parameters:

tokens
Array of Media Files tokens to destroy.

Returns:

HTTP Status 204:
Success, job queued.

Special Operations

GET
/api/v1/media_files/hashes.json?source= [DEPRECATED]

This call is deprecated and will be removed. Please use /api/v1/playlists/:playlist_token/hashes.json

Returns known file fingerprints for this account. Available only for local and cloud sources.

Available usually only for local and cloud media sources, this endpoint will return all MD5 fingerprints of the media files on this account. Useful to know what has already been uploaded.

It is recommended to filter by source because few other remote cloud services will also provide a file hash. If no source is specified the system will return all unique known hashes.

The local source represents files coming from AudioBox Desktop, the cloud source indicates media files stored on AudioBox Cloud.

Optional parameters:

source
'local', or 'cloud'

Returns:

HTTP Status 200:
Success.
HTTP Status 501:
Invalid source specified

POST
/api/v1/media_files/:token/scrobble.json

Notify the system that this media file finished playing.

This endpoint is highly recommended to be used and should be called when the Media File is approaching the end of the stream.

Triggers different actions in the system, such as Scrobbling to Last.fm and much more.

Returns:

HTTP Status 204:
Success, system handled the request.
HTTP Status 404:
Media File not found.
HTTP Status 503:
System overloaded or same job submitted too fast, please try again later.

GET
/api/v1/media_files/:token/lyrics.json

Shows the full informations of a media file plus lyrics.

Returns a representation of the media file completed with lyrics.

Returns:

HTTP Status 200:
Success.
HTTP Status 404:
Media File not found.

POST
/api/v1/media_files/:token/love.json

Manually 'love' a Media File

This will also trigger love/like on all supported and linked remote services, such as Last.fm/Facebook.

You can also 'love' the media file by issuing a PUT update request and setting the attribute 'loved' to true, but this will not notifying any remote services.

Last.fm will see a track as loved, Facebook as liked, Google Drive as starred, and so on.

Returns:

HTTP Status 204:
Success.

POST
/api/v1/media_files/:token/unlove.json

Manually 'unlove' a Media File

This will also trigger 'unlove' on all supported and linked remote services, such as Last.fm/Facebook/Google Drive.

You can also 'unlove' the media file by issuing a PUT update request and setting the attribute 'loved' to false, but this will not notifying any remote services.

Last.fm will see a track as unloved, Facebook as unliked, Google Drive as not starred, and so on.

Returns:

HTTP Status 204:
Success.

POST
/api/v1/media_files/:token/toggle_love.json

Switch the loved attribute to true/false and fire off remote services notifications.

This is useful for application that care about the loved attribute after it's being set.

Preserve all the functionalities of the love and unlove endpoints.

Returns:

HTTP Status 204:
Success.

Notifications API

GET
/api/v1/notifications.json

Returns a paginated collection of user's notifications.

Notifications are system messages that the AudioBox will send the user, for example when a Cloud Drive needs to be re-authenticated or if some operation fails.

There are four different notification levels: `error`, `success`, `info` and `warning`.

Optional parameters:

page
Number of the page. Default, non-changeable limit is 30 notifications per page.

Returns:

HTTP Status 200:
Success.

DELETE
/api/v1/notifications/:id.json

Permanently delete a notification by ID

Returns:

HTTP Status 204:
Success.
HTTP Status 404:
Not found.
Loading...