V5 API Documentation

This document describes version 5 of the Audiosocket MaaS™ API,
which provides easy access to our music search and streaming
features. The format and transport are JSON over HTTPS. The API is
versioned, and URLs look something like this:

https://api.audiosocket.com/v5/...

We bump the API version when we make incompatible changes to data
structures or remove features. New features, resources, and data do
not bump the API version, so please handle unknown keys
gracefully. New versions of the API are distributed along with a
release plan, including timelines for removing older versions of the
API.

Authentication

Access to the API is granted by your Audiosocket API token (to get or
reset yours, email us). Your token must be included with every
request you make in the X-Audiosocket-Token HTTP header.

All API calls are logged. If you wish to store additional audit
information about a request (e.g., the user in your system responsible
for initiating the call), you can optionally provide a tag in the
X-Audiosocket-Tag HTTP header.

(All examples will be presented as curl commands. If you’re on a
unixish system, curl is probably already available. In all examples,
SERVER is used instead of the actual API server name.)

Example: Provide an Audit Tag

Failures

API requests for missing or invalid API keys, inactive accounts, or
restricted resources will receive a 401 UNAUTHORIZED response with a
JSON body in the API’s standard error format:

{ "errors": { "request": ["Unauthorized."] } }

The "errors" object may contain additional information about the
issue, but is not intended for end-user display.

Attributes

The detailed documentation for each resource includes a list of
available attributes. In some cases, different data may be returned
depending on whether the resource is rendered in a scoped or unscoped
context.

For example, an album with ID 17 included in the
/artists/42/albums resource will not contain an attribute with
artist information, as it is implied by scope, but an unscoped
/albums/17 resource will.

Pagination

All top-level collection data returned by the API is paginated, and
all GET requests to collection resources accept the following optional
parameters:

Parameter

Description

p

Results Page (default is 1)

pp

Results Per Page (default is 100, capped at 1000)

All top-level collection data is returned in a consistent JSON
document format:

{
"data": [ ... ],
"page": 1,
"pages": 3,
"per": 50,
"total": 105
}

An empty result set is returned in the same format, with an empty
data array, total: 0, and pages: 1.

This resource returns a list of tracks matching the given
parameters. By default, results are ordered by relevance and
freshness. The example above searches for tracks related to “love” in
the “Blues” or “Rock” genres.

Many parameters take comma-separated lists of IDs. Depending on your
account, various search restrictions may be applied
automatically. Available query parameters (all optional):

g is a list of genre IDs, which specify the musical genres for a
track. Tracks can (and often do) belong to multiple genres, and
multiple IDs can be specified in this parameter. g=34,18 might
search for tracks that belong to the “Upbeat Rock” and “Latin Rock”
genres, for example.

Genres are organized in a two-level tree, so requests for a top-level
genre like “Rock” will also match tracks attached to any sub-genre of
“Rock.” See the /genres resource for a list of
valid genres.

i is a list of instrument IDs, which specify the musical instruments
used to perform the track. As with genres above, instruments are
organized in a tree and multiple comma-separated IDs can be
specified. See the /instruments resource
for a list of valid instruments.

o controls the sort order of search results. By default, search
results are returned in an order which favors newer, hotter
tracks. Order is specified as a list of comma-separated
attribute/direction pairs. For example, o=duration:desc,name:asc
would sort first by duration, favoring longer tracks, and then by
name, favoring track names starting at the begininng of the alphabet.

q is a free-text search, referencing artist names, album names,
track names, lyrics, the names of similar artists, and many of the
more structured classification elements as well. Any text may be
passed.

x is a flag specifying the explicit content of a track. Explicit
tracks may contain profanity or references to R-rated situations or
behavior. By default, both explicit and non-explicit tracks are
available. Set x=false to filter out explicit tracks.

Example: Download a 128k stereo MP3 of track 10005

To request a different quality or encoding variant, you can add extra
requirements to the track :id. A dot-separated list of requirements
must start with the requested quality in KBPS and the requested number
of channels (1 for mono, 2 for
stereo). Other requirements will be ignored unless your API account
has special powers.

Example: Download a 32k mono MP3 of track 10005

An authorized request to this URL will redirect you to a signed,
secure version of the track on one of our content delivery
network. Redirects are only valid for a few seconds, so don’t wait too
long to follow them. Requests for invalid or unavailable encodings
will return 404 NOT FOUND.

If you need a URL that’s accessible without authentication, you can
add /url for a JSON response. An optional lifetime parameter
(expressed in seconds) is supported. lifetime defaults to five
minutes, and can’t be longer than 12 hours.

/artists/:id/tracks

Rather than requiring requests to a bunch of discrete resources to get
the available genres, moods, tempos, et cetera, /context provides
everything in one big unpaginated data bomb. This is useful for
initialization: Make the big call at the beginning, and call the
specific resources if a refresh is necessary.

Each context value is equivalent to the contents of the data key on
a corresponding top-level resource request.

/moods/:ids/tracks

This resource exists for uptime and performance checking, and it’s the
only API method that can be requested without authentication.

curl http://SERVER/v5/ping

Response

{
ok: {
d: 38190,
m: 0,
r: [429, 40]
s: 1,
}
}

Success is defined as a 200 OK response with a JSON object
containing an ok key. The contents of ok can vary wildly depending
on account, cluster load, and time of day, and should be considered
opaque.

Tracks are the heart of the platform, and represent a playable piece
of music. Methods for Searching and streaming tracks are documented in detail
above. For speedy results, many track attributes are omitted when
showing results for a collection or search. All attributes can be
retrieved from the track’s /tracks/:id singular resource.

Response

Optional Attributes

Track search results are optimized for speed and delivery size by
default, but additional information can be requested by using the
with query parameter, which contains a comma-separated list of
additional attributes to include. Attribute abbreviations are
consistent with the query parameters from searching above.

/vocals/:ids/tracks

As Always, Thanks!

Please drop an email to api@audiosocket.com with any feature
requests, bug reports, or documentation improvements. We really
appreciate all feedback. We periodically send updates to
api-announce@audiosocket.com: If there are folks in your
organization who would like to receive API updates, please let us
know.