Getting started with the Audiomack API
Favorite / unfavorite a song or album
Repost or un-repost a song or album
Search songs, albums & artists
Introduction
The Audiomack API provides a programmatic interface to the music data on audiomack.com
Getting started with the Audiomack API
General
The Audiomack base endpoint lives at https://api.audiomack.com/v1
Note that requests to the API must be sent over HTTPS.
The API uses the oAuth 1.0a protocol.
All API responses are in JSON format.
Filtering
Most GET requests can be filtered so that only particular fields are returned.
Just add a fields
parameter which can take a comma separated list of field names. These field names will be the only fields returned in the response. Without a fields
parameter, ALL fields will be returned.
As an example, to just return ID's from the artists favorites call, you can use the following request structure:
GET /v1/artist/glen-scott/favorites?show=music&fields=id
You can also override the default 20 number of items that are returned. You can do this by passing a limit
parameter. Passing a limit of 0 will return ALL results. Without a limit parameter, 20 results will be returned.
Example of combining the fields
and limit
parameters to return ALL artist favorite ID's:
GET /v1/artist/glen-scott/favorites?show=music&fields=id&limit=0
Sub fields can also be returned by using a field:sub field notation. For example, to return an artist's name along with a title, image and ID when retrieving chart items, you could use:
GET /v1/chart/playlists/weekly?fields=artist:name,title,image,id
Pagination
Many endpoints return more than one result. By default, 20 results will be returned at any one time. More results can be fetched by appending a /page/X
to the endpoint's path, where X is an integer page number.
/page/1
is the first 20 results (1-20)/page/2
is the second 20 results (21-40) etc.
Example paginated request -- retrieving the second page of most recent music results:
GET /v1/music/recent/page/2
The total number of results available will be shown in the count
field in the response:
{
"results": [
],
"count": 231
}
Note: the page value must come before any query parameters, for example:
GET /v1/music/recent/page/2?fields=id
To return all results in one go, pass a limit parameter of zero, for example:
GET /v1/music/recent?limit=0
Authenticated Requests
Certain endpoints require a valid Audiomack user login to perform. For example, favoriting a song or album requires us to know who is currently logged in.
Authenticated requests follow the standard OAuth 1.0a Authentication Flow:
- The Consumer obtains an unauthorized Request Token.
- The User authorizes the Request Token.
- The Consumer exchanges the Request Token for an Access Token.
Terms used:
- Service Provider
- A web application that allows access via OAuth.
- Consumer
- A website or application that uses OAuth to access the Service Provider on behalf of the User.
- Request Token
- A value used by the Consumer to obtain authorization from the User, and exchanged for an Access Token.
Rather than manually creating code for OAuth, we recommend instead using one of the pre-built libraries available for your programming language.
Obtaining an Unauthorized Request Token
As described in 6.1 Obtaining an Unauthorized Request Token.
The Consumer obtains an unauthorized Request Token by asking the Service Provider to issue a Token. The Request Token's sole purpose is to receive User approval and can only be used to obtain an Access Token. The Request Token process goes as follows:
POST /v1/request_token
The request must be signed and contain the following additional parameter:
oauth_callback
- An absolute URL to which the Service Provider will redirect the User back when the Obtaining User Authorization step is completed. If the Consumer is unable to receive callbacks or a callback URL has been established via other means, the parameter value MUST be set tooob
(case sensitive), to indicate an out-of-band configuration. required
Response:
oauth_token=foo&oauth_token_secret=bar&oauth_callback_confirmed=true
Note that request tokens are valid for one hour after creation.
Obtaining User Authorization
As described in 6.2 Obtaining User Authorization
The Consumer cannot use the Request Token until it has been authorized by the User. Obtaining User authorization includes the following steps:
GET https://www.audiomack.com/oauth/authenticate?oauth_token=foo
The request MUST NOT be signed (i.e. no oauth_*
parameters other than the oauth_token
are required)
Parameters:
oauth_token
- The Request Token obtained in the previous step. required
Response:
The User will be shown a login screen and be given the option to authorize the Consumer. After the User has authorized your application, they will be redirected to the callback URL along with two additional GET parameters:
oauth_token
- the request token the User authorizedoauth_verifier
- The verification code
Obtaining an Access Token
The Consumer exchanges the Request Token for an Access Token capable of accessing the Protected Resources. Obtaining an Access Token includes the following steps:
POST /v1/acccess_token
This is an OAuth signed request
Parameters:
oauth_consumer_key
- The Consumer Keyoauth_token
- The Request Token obtained previously.oauth_signature_method
- The signature method the Consumer used to sign the request.oauth_signature
- The signature as defined in Signing Requests.oauth_timestamp
- As defined in Nonce and Timestamp.oauth_nonce
- As defined in Nonce and Timestamp.oauth_verifier
- The verification code received from the Service Provider in the Service Provider Directs the User Back to the Consumer step.
Response:
On successful validation, an access token will be returned:
oauth_token=foo&doauth_token_secret=bar
This access token can now be used to access resources on behalf of the user.
An example PHP application demonstrating the authentication flow can be used as a reference for your own implementation.
Access tokens will expire 1 year after they are created. Along with the access token, you will receive the expiration time as a UNIX timestamp. This means that once you have requested an access token for a user, you can save it locally and use it for future requests until the expiration date. After the expiration, you should request a new access token from /v1/access_token
.
Please note: you should plan for the event that a user's access token becomes invalid, and re-authorize in that case.
If you send a request with an expired or invalid access token, you will receive a 401 Unauthorized
HTTP status along with the following response:
{"errorcode":1003,"message":"Invalid access token: 52494a447932cdf828fdd71ef78d6ac6"}
Error Handling
The API will return an appropriate HTTP status code which can help API consumers route responses accordingly. If the HTTP status code is not 200 OK
then a problem has occurred. 4XX and 5XX status code indicate an error on the client or server side, respectively.
As well as the status code, an error payload will be returned in the response body.
Example 1 - standard error with description:
{"errorcode":1002,"message":"The artist you requested could not be found."}
Example 2 - validation errors:
{"errorcode":1008,"message":"Validation failed","errors":{"email":{"isEmpty":"This field is required"},"password2":{"notSame":"The passwords entered do not match"}}}
The following fields are included:
- errorcode
- message
- description (optional)
- errors (optional)
errorcode
and message
are always returned. A description
will be returned in some cases when a more detailed explanation is available. When several errors have been found -- for example, during validation of a form -- the errors
field will contain an array detailing the errors found.
List of possible errors
API error code | HTTP status code | Message | Explanation |
---|---|---|---|
1000 | 422 | Music is already favorited | |
1001 | 422 | Cannot unfavorite music that is not a favorite | |
1002 | 404 | The artist you requested could not be found | |
1003 | 401 | (several possible) | The oAuth signature was not valid |
1004 | 401 | Request unauthorised | The endpoint requires a valid access token |
1005 | 404 | Song was not found | |
1006 | 503 | User details could not be retrieved | |
1007 | 503 | Could not create new access token | |
1008 | 422 | Validation failed | Details will be available in errors array |
1009 | 422 | Username and password must be supplied to retrieve an access token | |
1010 | 503 | Artist details could not be retrieved | |
1011 | 500 | The password reset email could not be sent |
Example Code - PHP
The following PHP examples use the official PHP oAuth library (http://php.net/manual/en/book.oauth.php)
Non-authenticated request:
<?php
$api_base = 'https://api.audiomack.com/v1';
$conskey = 'your_consumer_key';
$conssec = 'your_consumer_secret';
try {
$oauth = new OAuth($conskey,$conssec);
$oauth->fetch($api_base . '/debug');
$json = json_decode($oauth->getLastResponse());
print_r($json);
}
catch(OAuthException $E) {
print_r($E);
}
Result
Debug
The above example requires the installation of the OAuth extension. An alternative is to use the Composer-based HTTP_OAuth library which can be installed as follows:
composer require pear/http_oauth
<?php
$api_base = 'https://api.audiomack.com/v1';
$consumer = new HTTP_OAuth_Consumer('your_consumer_key', 'your_consumer_secret');
$res = $consumer->sendRequest($api_base . '/artist/aboogiewitdahoodie', [], 'GET');
$data = json_decode($res->getResponse()->getBody(), true);
Image Sizes
Entities will often have an associated image. For example, a music entity may have some artwork that represents the song or album. By default, images will be 275 pixels in width and 275 pixels in height.
The original image may be requested by appending the parameter image_size=original
to your request URL. In this case, the image field will contain the original image, rather than the default size. The original image may be up to 1600 x 1600 pixels in size.
Entities
Music
The following JSON object represents a song:
{
"id":"162",
"stream_only":"no",
"image":"https:\/\/assets.dev.audiomack.com\/justa-test\/d6f69aed1e71c67ae012d4e20665d7fb.jpeg",
"buy_link":"",
"title":"Last in Class",
"uploaded":"1381525447",
"producer":"",
"updated":"1384308009",
"description":"Contrary to <a href='#'>popular belief<\/a>, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. \r\n\r\nRichard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, and going through the cites of the word in classical literature, discovered the undoubtable source. Lorem Ipsum comes from sections 1.10.32 and 1.10.33 of \"de Finibus Bonorum et Malorum\" (The Extremes of Good and Evil) by Cicero, written in 45 BC. \r\n\r\nThis book is a treatise on the theory of ethics, very popular during the Renaissance. The first line of Lorem Ipsum, \"Lorem ipsum dolor sit amet..\"",
"type":"song",
"genre":"",
"uploader":{
"id":"5",
"updated":"1384306306",
"hometown":"Moorhead",
"created":"1329493435",
"facebook":"",
"url_slug":"justa-test",
"label":"Whatevz",
"name":"Justa Test",
"genre":"Hip Hop \/ Rap",
"image":"https:\/\/assets.dev.audiomack.com\/justa-test\/d6f69aed1e71c67ae012d4e20665d7fb.jpeg",
"url":"https:\/\/audiomack.com",
"twitter":"tywangsness",
"bio":"Contrary to <a href='#'>popular belief<\/a>, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, and going through the cites of the word in classical literature, discovered the undoubtable source. Lorem Ipsum comes from sections 1.10.32 and 1.10.33 of \"de Finibus Bonorum et Malorum\" (The Extremes of Good and Evil) by Cicero, written in 45 BC. This book is a treatise on the theory of ethics, very popular during the Renaissance. The first line of Lorem Ipsum, \"Lorem ipsum dolor sit amet..\"",
"verified":"yes"
},
"featuring":"",
"album":"",
"url_slug":"last-in-class",
"artist":"Something",
"released":"1381525467",
"status":"complete",
"time_ago":"11 months ago",
"live":true,
"streaming_url":"https:\/\/songs.dev.audiomack.com\/streaming\/justa-test\/last-in-class.mp3?Expires=1411644853&Signature=b4xEeDXPgOnSLs1yDqtUv3FT2IFruYKT-yfjLq19NszenDaRqCwQVCvFHA3Ye1C7JkY-XMjI-KbLJXbkAa3WUZnP1DtMAnbPx9qmJsKljEQN9hlqDK-IxI1Q5uleZw6OYonT3s2J42pBJ~RuaLN6q4LMaZIE-1GW3aGoav86gsI_&Key-Pair-Id=APKAIKAIRXBA2H7FXITA",
"streaming_url_timeout":1411644853
}
- The
streaming_url
is the path to the MP3 track. The link is only valid for approximately 10 seconds so should be (re-)requested just before the track needs to be played.
Artist
{
"id": "46",
"name": "Glen Mark Scott",
"url_slug": "glen-scott",
"image": "https:\/\/assets.dev.audiomack.com\/default-artist-image.png",
"hometown": "",
"bio": "Bio - edited",
"twitter": "glenscott",
"facebook": "https:\/\/facebook.com\/glen.scott.716",
"instagram": "glenscott",
"label": "",
"url": "",
"genre": "electronic",
"verified": "",
"updated": "1426519369",
"created": "1409298867",
"status": "active",
"video_ads": "yes",
"follow_download": "yes",
"follow_count": 2,
"upload_count": 10,
"favorites_count": 9,
"playlists_count": 44,
"following_count": 3,
"followers_count": 2,
"feed_count": 160
}
User
This entity represents the authenticated user.
Endpoints
Music
Song or album info
There are two ways of getting song or album details. Option 1, using a music ID:
GET /v1/music/:id
Option 2, using an artist and music slug:
GET /v1/music/(song|album)/(artist slug)/(song or album slug)
Parameters:
key
(optional) promotional key for private tracks
Most recent
GET /v1/music/recent
Response format:
{
"results":[],
"count": 23
}
results
contains an array of music entities. count
contains the total number of results found.
Genre-specific most recent
GET /v1/music/(genre)/recent
Response format:
{
"results":[],
"count": 23
}
results
contains an array of music entities. count
contains the total number of results found.
Trending
GET /v1/music/trending
Response format:
{
"results":[],
"count": 23
}
results
is an array containing details of each music item (song or album). count
contains the total number of results found.
Genre-specific Trending
GET /v1/music/(genre)/trending
Genre can be one of:
- rap
- electronic
Flagging Unplayable Tracks
PATCH /v1/music/(song|album)/(artist slug)/(song or album slug)
Parameters:
status = unplayable
There may be times when a track is unable to be played. For example, if the streaming source returns a 404. When this happens, you can send a notification that the track in unplayable and a website administrator will take further actions.
Play a Track
POST /v1/music/:id/play
session
- (optional) unique user session identifieralbum_id
- (optional) album that the track belongs toplaylist_id
- (optional) playlists that the track belongs tohq
- (optional) retrieve the highest quality streaming sourcekey
(optional) promotional key for private tracks
This returns the tracks streaming source.
Example response:
"https:\/\/songs.dev.audiomack.com\/streaming\/curreny\/corvette-doors.mp3?Expires=1412078706&Signature=AqOdPwjhJrbWeAptHiqBcDnf-H9mreYAsRUx88QDoIMnni85L7DmhgKGagOGMbqkazei6lKmhOSW~XNjREl~ggWaz0k6GMC7C4lmasbf0bCdPwpJ25IIVtL8TxEKEEj5L4jhy8CdyAjs6VW31dK3KcchkrrnsDXF6Ghh1SOA7~I_&Key-Pair-Id=APKAIKAIRXBA2H7FXITA"
The session
parameter is required for tracking play statistics. For applications running on mobile devices, the mobile device unique ID can be used for the session value.
Track an ad
POST /v1/music/:id/ads
Parameters:
status
- (required) one of the following:requested
,loaded
,started
,skipped
,completed
,error
Example response:
A successful favorite or unfavorite returns HTTP Status code 204 (No Content)
Favorite / unfavorite a song or album
Favoriting or unfavoriting requires a valid access token to be sent as part of the request.
PUT /v1/music/:id/favorite
DELETE /v1/music/:id/favorite
Example response:
A successful favorite or unfavorite returns HTTP Status code 204 (No Content)
Repost or un-repost a song or album
Reposting or un-reposting requires a valid access token to be sent as part of the request.
PUT /v1/music/:id/repost
DELETE /v1/music/:id/repost
Example response:
A successful repost or un-repost returns HTTP Status code 204 (No Content).
Metrics
Get metrics grouped by event type for the music object, for events happened within last 60 minutes.
GET /v1/music/:id/metrics
Response, JSON object wrapped in results
:
event_counters
- object with counters where attribute is "event_type" string and value is "count"
Response example:
{
"results":
{
"event_counters":
{
"play": 345,
"repost": 15
}
}
}
Artists
Artist information is retrieved using a slug
(URL-friendly version of the artist's name). The slug is present in music entities under uploader -> url_slug
Artist Information
GET /v1/artist/(artist slug)
Example response:
{
"results": {
"id": "46",
"name": "Glen Mark Scott",
"url_slug": "glen-scott",
"image": "https:\/\/assets.dev.audiomack.com\/default-artist-image.png",
"hometown": "",
"bio": "Bio - edited",
"twitter": "glenscott",
"facebook": "https:\/\/facebook.com\/glen.scott.716",
"instagram": "glenscott",
"label": "",
"url": "",
"genre": "electronic",
"verified": "",
"updated": "1426519369",
"created": "1409298867",
"status": "active",
"video_ads": "yes",
"follow_download": "yes",
"follow_count": 2,
"upload_count": 10,
"favorites_count": 9,
"playlists_count": 44,
"following_count": 3,
"followers_count": 2,
"feed_count": 160
}
}
Artist Uploads
To get music uploaded by a particular artist:
GET /v1/artist/(artist slug)/uploads
This endpoint supports pagination.
Artist Favorites
GET /v1/artist/(artist slug)/favorites
This returns an array of music objects that the artist has favorited. The results can be filtered by type by sending an extra parameter:
show
- filter the results. The default isall
. Other options aremusic
(songs & albums),song
,album
orplaylist
.
Artist favorites search
To search within an artist's favorites (songs & albums only):
GET /v1/artist/(artist slug)/favorites/search
Parameters:
q
- the text to search for
Artist playlists
GET /v1/artist/(artist slug)/playlists
{
"results": [
{
"id": "20",
"artist_id": "46",
"url_slug": "api-created-playlist-11",
"genre": "rap",
"created": "1417701853",
"updated": "1417701853",
"private": "no",
"type": "playlist",
"artist": {
"id": "46",
"name": "Glen Scott",
"url_slug": "glen-scott",
"image": "https:\/\/assets.dev.audiomack.com\/default-artist-image.png",
"hometown": "",
"bio": "",
"twitter": "glenscott",
"facebook": "",
"instagram": "",
"label": "",
"url": "",
"genre": "electronic",
"verified": "",
"updated": "1412328536",
"created": "1409298867",
"status": "active"
},
"track_count": 1,
"time_ago": "1 hour ago",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/36b791b59a4152d96268c65b63fb0097.jpeg",
"title": "API-created playlist"
},
...
Artist playlists can be optionally filtered by genre by adding a genre parameter:
GET /v1/artist/(artist slug)/playlists?genre=rap
This endpoint supports pagination.
Follow or unfollow an artist
An authenticated user can follow or unfollow another artist using the following methods:
Follow an artist:
PUT /v1/artist/(artist slug)/follow
Unfollow an artist:
DELETE /v1/artist/(artist slug)/follow
Both methods will return a 204 No Content HTTP status code if the action is successful.
Artist Following
To retrieve the artists that an artist is following:
GET /v1/artist/(artist slug)/following
This will return an array of artists under the results
key:
{
"results": [
{
"id": "17",
"name": "Macli",
"url_slug": "macli",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/82629541ba67f5819b529e33bec0421d.jpeg",
"hometown": "Brooklyn",
"bio": "This is my bio...",
"twitter": "djboothceo",
"facebook": "https:\/\/www.facebook.com\/djboothnet",
"label": "Serious",
"url": "http:\/\/www.djbooth.net",
"genre": "electronic",
"verified": "",
"created": "1331147520",
"updated": "1384287595"
},
{
"id": "4",
"name": "Curren$y",
"url_slug": "curreny",
"image": "https:\/\/assets.dev.audiomack.com\/curreny\/fe68a9fabbda3311110dd661f5097993.jpg",
"hometown": "New Orleans",
"bio": "currensybooking@gmail.com Jets......Fool.....",
"twitter": "currensy_spitta",
"facebook": "https:\/\/www.facebook.com\/CurrenSy",
"label": "Jet Life Recordings",
"url": "",
"genre": "",
"verified": "",
"created": "1328903279",
"updated": "1384287594"
}
]
}
Artist Followers
To retrieve the artists that are following an artist:
GET /v1/artist/(artist slug)/follows
As with the artist following call, the response will contain an array of artists under the results
key.
Artist feed
Retrieve music from an artist's feed.
GET /v1/artist/(artist slug)/feed
This endpoint supports pagination.
Reposts
Some artist endpoints return music items that have been reposted
by an artist. Reposted items have been uploaded by other artists.
Reposted items can be distinguished by the presence of a repost
attribute on the song or album. This attribute contains the artist name that reposted the item.
Reposts may appear in the following endpoints:
- Artist upload
- Artist feed
Metrics
Get metrics grouped by event type for the artist and top 10 music objects, for events happened within last 60 minutes.
GET /v1/artist/:id/metrics
Response, JSON object wrapped in results
:
event_counters
- object with counters where attribute is "event_type" string and value is "count"music_top10
- list of top 10 music objects ordered by plays count, each item contains:music
- music objectplay_counter
- plays counter
Response example:
{
"results":
{
"event_counters":
{
"play": 345,
"favorite": 15
},
"music_top10":
[
{
"music": { ... },
"play_counter": 200
},
{
"music": { ... },
"play_counter": 183
},
...
]
}
}
Charts
Chart Tracks
GET /v1/chart/(songs|albums|playlists)/(chart type)
chart type
must be one of the following:
- total
- daily
- weekly
- monthly
- yearly
Genre-specific chart tracks
GET /v1/(genre)/chart/(songs|albums|playlists)/(chart type)
Search
Search songs, albums & artists
GET /search
Parameters:
q
- the text to search forshow
- (optional) filter results by type. possible values are "songs", "albums", "artists" or "music". "music" fetches ALL types, which is the default behaviour if no show parameter is passed.sort
- (optional) one ofrelevance
,recent
orpopular
. If no option is passed, relevance sorting is used.page
- (optional) which page of results you wish to view. If no page is specified, the first page of results if returnedlimit
- (optional) by default, 20 results are returned per page. By setting the limit, you can change this.genre
- (optional) by default, items in all genres are searched. By setting this parameter you can restrict searches to specific genres. Example genres values:rap
,electronic
anddancehall
.verified
- (optional) to restrict results from verified accounts, set this parameter
Search autosuggest
GET /search_autosuggest
Parameters:
q
- the text to search for
Stats
Get stats token
A stats token is required to record stats. A token should be requested whenever a user views details of a song or album.
GET /v1/music/stats/token
Parameters required:
device
- a unique ID of the requesting device or user as an MD5 hash.music_id
Example response:
"XaBDqwscvRr\/fA1RJzVJJv2s3Ue43puyCml1ljqs9Vr08K8P"
Record Stats
POST /v1/music/stats/(music id)
Parameters required:
token
- the stats token that was previously requestedtype
- eitherpv
to signify details of a song or album have been viewed, orplay
to signify a track has been played
The token only has to be requested once per song or album. Multiple plays of the same song/album can be registered against the same token.
Playlists
Trending
GET /v1/playlist/trending
Example response:
{
"results": [
{
"id": 5,
"artist_id": "46",
"url_slug": "five-alive",
"genre": "rap",
"created": "1409302862",
"updated": "1409302862",
"private": "no",
"type": "playlist",
"artist": {
"id": "46",
"name": "Glen Scott",
"url_slug": "glen-scott",
"image": "https:\/\/assets.dev.audiomack.com\/default-artist-image.png",
"hometown": "",
"bio": "Bio - edited",
"twitter": "glenscott",
"facebook": "",
"instagram": "",
"label": "",
"url": "",
"genre": "electronic",
"verified": "",
"updated": "1418134702",
"created": "1409298867",
"status": "active",
"video_ads": "1"
},
"track_count": 6,
"time_ago": "3 months ago",
"image": "https:\/\/assets.dev.audiomack.com\/justa-test\/85c1b0c659a74b47ce9fb6163f89ebe2.jpeg",
"title": "Five Alive"
}
],
"count": 1
}
results
is an array containing details of each playlist item. count contains the total number of results found.
Genre-specific trending
GET /v1/playlist/(genre)/trending
Genre can be one of:
- rap
- electronic
Create playlist
Creating a playlist requires a valid access token to be sent as part of the request.
POST /v1/playlist
Parameters:
title
- The title of the playlistgenre
- The genre of the playlist. Must be one of the accepted Genre codes -- see belowprivate
- (optional) "yes" or "no" to indicate whether the playlist is only viewable by the creator. Defaults tono
.music_id
- (optional) a song that will be added to the newly-created playlist. Multiple songs can be added at once by comma-separating the ID's for example,1,2,3
image
- (optional) The playlist artwork. Base64 encoded JPEG or PNG image data. Maximum size (before encoding) 2Mb.
Acceptable genre codes:
- rap (for Hip-Hop/R&B)
- electronic
- rock
- pop
- other
Example responses:
HTTP Status 201
A link to the created resource will be returned in the Location header
The new playlist is also returned as part of the response body
{
"id": 12,
"artist_id": "46",
"url_slug": "api-created-playlist-3",
"genre": "rap",
"created": "1417694974",
"updated": "1417694974",
"private": "no",
"type": "playlist",
"artist": {
"id": "46",
"name": "Glen Scott",
"url_slug": "glen-scott",
"image": "https:\/\/assets.dev.audiomack.com\/default-artist-image.png",
"hometown": "",
"bio": "",
"twitter": "glenscott",
"facebook": "",
"instagram": "",
"label": "",
"url": "",
"genre": "electronic",
"verified": "",
"updated": "1412328536",
"created": "1409298867",
"status": "active"
},
"track_count": 0,
"time_ago": " ago",
"image": "https:\/\/assets.dev.audiomack.com\/default-artist-image.png",
"title": "API-created playlist"
}
Playlist could not be created:
HTTP Status 503
{
"errorcode": 1017,
"message": "Playlist could not be created"
}
Edit playlist
PUT /v1/playlist/:id
Parameters:
title
- The title of the playlistgenre
- The genre of the playlist. Must be one of the accepted Genre codes -- see belowmusic_id
- (optional) one or more music ID's that make up the playlist. Multiple music ID's should be separated by commasprivate
- (optional) "yes" or "no" to indicate whether the playlist is only viewable by the creator. Defaults tono
.image
- (optional) The playlist artwork. Base64 encoded JPEG or PNG image data. Maximum size (before encoding) 2Mb.
Example responses:
A successful edit results in a 200/OK status and the new playlist entity returned in the body.
HTTP Status 200
{
"id": "31",
"artist_id": "46",
"url_slug": "sooper-dooper",
"genre": "electronic",
"created": "1419263858",
"updated": "1419335302",
"private": "no",
"type": "playlist",
"artist": {
"id": "46",
"name": "Glen Scott",
"url_slug": "glen-scott",
"image": "https:\/\/assets.dev.audiomack.com\/default-artist-image.png",
"hometown": "",
"bio": "Bio - edited",
"twitter": "glenscott",
"facebook": "",
"instagram": "",
"label": "",
"url": "",
"genre": "electronic",
"verified": "",
"updated": "1418134702",
"created": "1409298867",
"status": "active",
"video_ads": "1"
},
"track_count": 2,
"time_ago": "1 hour ago",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/36b791b59a4152d96268c65b63fb0097.jpeg",
"oldname": "Sooper Dooper",
"oldgenre": "electronic",
"title": "Sooper Dooper",
"tracks": [
{
"id": "56",
"buy_link": "",
"url_slug": "respect-game-or-expect-flames-f-del-the-funky-homosapien",
"type": "song",
"featuring": "",
"stream_only": "",
"uploaded": "1345654548",
"album": "",
"updated": "1373625916",
"released": "1345654548",
"artist": "Casual",
"title": "Respect Game Or Expect Flames f. Del The Funky Homosapien",
"genre": "",
"description": "",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/36b791b59a4152d96268c65b63fb0097.jpeg",
"status": "complete",
"uploader": {
"id": "17",
"name": "Macli",
"url_slug": "macli",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/82629541ba67f5819b529e33bec0421d.jpeg",
"hometown": "Brooklyn",
"bio": "This is my bio...",
"twitter": "djboothceo",
"facebook": "http:\/\/www.facebook.com\/djboothnet",
"label": "Serious",
"url": "http:\/\/www.djbooth.net",
"genre": "electronic",
"verified": "",
"created": "1331147520",
"updated": "1384287595"
},
"producer": "",
"time_ago": "2 years ago",
"live": true,
"streaming_url": "https:\/\/songs.dev.audiomack.com\/streaming\/macli\/respect-game-or-expect-flames-f-del-the-funky-homosapien.mp3?Expires=1419345627&Signature=fetTGiBUxPbQ5yLyD7GCo0tMmnX7hGZravistBXdl7-o37QVGIF0XW~JJcH0tdCvuyrdwL93DfgqDem3AsA5dzarjeuijrF0kgxzstYVZslfTfiCXxds1gepbIuY7zTqZg-pedHZKOi-3wCJgNZnLbs~QN5Zit8AESqZbwDTSUw_&Key-Pair-Id=APKAIKAIRXBA2H7FXITA",
"streaming_url_timeout": 1419345627
},
{
"id": "57",
"uploader": {
"id": "17",
"name": "Macli",
"url_slug": "macli",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/82629541ba67f5819b529e33bec0421d.jpeg",
"hometown": "Brooklyn",
"bio": "This is my bio...",
"twitter": "djboothceo",
"facebook": "http:\/\/www.facebook.com\/djboothnet",
"label": "Serious",
"url": "http:\/\/www.djbooth.net",
"genre": "electronic",
"verified": "",
"created": "1331147520",
"updated": "1384287595"
},
"type": "song",
"title": "Don't Let Me Down 2012",
"url_slug": "dont-let-me-down-2012",
"artist": "Gramatik Vs. The Beatles",
"album": "Thissongissick.com",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/e9d79beb457c8f24740eb501dd981a2c.jpeg",
"featuring": "",
"producer": "",
"description": "",
"uploaded": "1345655077",
"released": "1345655077",
"updated": "1373625916",
"status": "complete",
"genre": "",
"stream_only": "",
"buy_link": "",
"time_ago": "2 years ago",
"live": true,
"streaming_url": "https:\/\/songs.dev.audiomack.com\/streaming\/macli\/dont-let-me-down-2012.mp3?Expires=1419345627&Signature=FLgn5RcJvsVyoEiDXjcipETeDP2LtXqGufYuUaDgxmpWaoFwU2ReltQrUzegJWMGZPmkKgVn3mEu0jRi2MOcKePXUFSDWfjFb8Xh5tH44AAttIjt4y8T1GtMUWNoQQ3ii6ij7hhkqaJhNAZHnf4IUnJ-txo4Kh~8Ozt6X4AxXt4_&Key-Pair-Id=APKAIKAIRXBA2H7FXITA",
"streaming_url_timeout": 1419345627
}
]
}
Delete playlist
This removes a playlist owned by the currently authenticated user.
DELETE /v1/playlist/:id
A successful deletion returns HTTP Status code 204 (No Content)
Add song(s) to playlist
POST /v1/playlist/(playlist id)/track
Parameters:
music_id
- The song that should be added to the playlist. Multiple songs can be added at once by comma-separating the ID's for example,1,2,3
Successful response:
HTTP Status 201 (Created)
and the updated playlist(s) in the body of the response.
{
"id": "31",
"artist_id": "46",
"url_slug": "sooper-dooper",
"genre": "electronic",
"created": "1419263858",
"updated": "1419335302",
"private": "no",
"type": "playlist",
"artist": {
"id": "46",
"name": "Glen Scott",
"url_slug": "glen-scott",
"image": "https:\/\/assets.dev.audiomack.com\/default-artist-image.png",
"hometown": "",
"bio": "Bio - edited",
"twitter": "glenscott",
"facebook": "",
"instagram": "",
"label": "",
"url": "",
"genre": "electronic",
"verified": "",
"updated": "1418134702",
"created": "1409298867",
"status": "active",
"video_ads": "1"
},
"track_count": 2,
"time_ago": "1 hour ago",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/36b791b59a4152d96268c65b63fb0097.jpeg",
"oldname": "Sooper Dooper",
"oldgenre": "electronic",
"title": "Sooper Dooper",
"tracks": [
{
"id": "56",
"buy_link": "",
"url_slug": "respect-game-or-expect-flames-f-del-the-funky-homosapien",
"type": "song",
"featuring": "",
"stream_only": "",
"uploaded": "1345654548",
"album": "",
"updated": "1373625916",
"released": "1345654548",
"artist": "Casual",
"title": "Respect Game Or Expect Flames f. Del The Funky Homosapien",
"genre": "",
"description": "",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/36b791b59a4152d96268c65b63fb0097.jpeg",
"status": "complete",
"uploader": {
"id": "17",
"name": "Macli",
"url_slug": "macli",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/82629541ba67f5819b529e33bec0421d.jpeg",
"hometown": "Brooklyn",
"bio": "This is my bio...",
"twitter": "djboothceo",
"facebook": "http:\/\/www.facebook.com\/djboothnet",
"label": "Serious",
"url": "http:\/\/www.djbooth.net",
"genre": "electronic",
"verified": "",
"created": "1331147520",
"updated": "1384287595"
},
"producer": "",
"time_ago": "2 years ago",
"live": true,
"streaming_url": "https:\/\/songs.dev.audiomack.com\/streaming\/macli\/respect-game-or-expect-flames-f-del-the-funky-homosapien.mp3?Expires=1419345627&Signature=fetTGiBUxPbQ5yLyD7GCo0tMmnX7hGZravistBXdl7-o37QVGIF0XW~JJcH0tdCvuyrdwL93DfgqDem3AsA5dzarjeuijrF0kgxzstYVZslfTfiCXxds1gepbIuY7zTqZg-pedHZKOi-3wCJgNZnLbs~QN5Zit8AESqZbwDTSUw_&Key-Pair-Id=APKAIKAIRXBA2H7FXITA",
"streaming_url_timeout": 1419345627
},
{
"id": "57",
"uploader": {
"id": "17",
"name": "Macli",
"url_slug": "macli",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/82629541ba67f5819b529e33bec0421d.jpeg",
"hometown": "Brooklyn",
"bio": "This is my bio...",
"twitter": "djboothceo",
"facebook": "http:\/\/www.facebook.com\/djboothnet",
"label": "Serious",
"url": "http:\/\/www.djbooth.net",
"genre": "electronic",
"verified": "",
"created": "1331147520",
"updated": "1384287595"
},
"type": "song",
"title": "Don't Let Me Down 2012",
"url_slug": "dont-let-me-down-2012",
"artist": "Gramatik Vs. The Beatles",
"album": "Thissongissick.com",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/e9d79beb457c8f24740eb501dd981a2c.jpeg",
"featuring": "",
"producer": "",
"description": "",
"uploaded": "1345655077",
"released": "1345655077",
"updated": "1373625916",
"status": "complete",
"genre": "",
"stream_only": "",
"buy_link": "",
"time_ago": "2 years ago",
"live": true,
"streaming_url": "https:\/\/songs.dev.audiomack.com\/streaming\/macli\/dont-let-me-down-2012.mp3?Expires=1419345627&Signature=FLgn5RcJvsVyoEiDXjcipETeDP2LtXqGufYuUaDgxmpWaoFwU2ReltQrUzegJWMGZPmkKgVn3mEu0jRi2MOcKePXUFSDWfjFb8Xh5tH44AAttIjt4y8T1GtMUWNoQQ3ii6ij7hhkqaJhNAZHnf4IUnJ-txo4Kh~8Ozt6X4AxXt4_&Key-Pair-Id=APKAIKAIRXBA2H7FXITA",
"streaming_url_timeout": 1419345627
}
]
}
Remove song from playlist
DELETE /v1/playlist/(playlist id)/(music id)
Successful response:
A successful deletion results in HTTP Status 204 (No Content)
Get playlist info
There are two ways of getting playlist info and details. Option 1, using a playlist ID:
GET /v1/playlist/:id?fields=title,image,track_count
Option 2, using an artist and playlist slug:
GET /v1/playlist/:artistSlug/:playlistSlug?fields=title,image,track_count
Example responses:
Successful response:
{
"results": {
"track_count": 4,
"image": "https:\/\/assets.dev.audiomack.com\/justa-test\/d6f69aed1e71c67ae012d4e20665d7fb.jpeg",
"title": "My First Playlist!"
}
}
Get playlist details
GET /v1/playlist/:id
GET /v1/playlist/:artistSlug/:playlistSlug
Example responses:
Successful response:
{
"results": {
"id": "1",
"artist_id": "46",
"url_slug": "my-first-playlist",
"genre": "rap",
"created": "1409299195",
"updated": "1409299195",
"private": "no",
"type": "playlist",
"artist": {
"id": "46",
"name": "Glen Scott",
"url_slug": "glen-scott",
"image": "https:\/\/assets.dev.audiomack.com\/default-artist-image.png",
"hometown": "",
"bio": "",
"twitter": "glenscott",
"facebook": "",
"instagram": "",
"label": "",
"url": "",
"genre": "electronic",
"verified": "",
"updated": "1412328536",
"created": "1409298867",
"status": "active"
},
"track_count": 4,
"time_ago": "3 months ago",
"image": "https:\/\/assets.dev.audiomack.com\/justa-test\/d6f69aed1e71c67ae012d4e20665d7fb.jpeg",
"title": "My First Playlist!",
"tracks": [
{
"id": "162",
"title": "<script>alert('Last in Class')</script>",
"album": "",
"uploaded": "1381525447",
"buy_link": "",
"type": "song",
"artist": "Something",
"url_slug": "last-in-class",
"status": "complete",
"uploader": {
"id": "5",
"image": "https:\/\/assets.dev.audiomack.com\/justa-test\/d6f69aed1e71c67ae012d4e20665d7fb.jpeg",
"url_slug": "justa-test",
"verified": "yes",
"label": "Whatevz",
"bio": "Contrary to >a href='#'>popular belief>/a>, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, and going through the cites of the word in classical literature, discovered the undoubtable source. Lorem Ipsum comes from sections 1.10.32 and 1.10.33 of \"de Finibus Bonorum et Malorum\" (The Extremes of Good and Evil) by Cicero, written in 45 BC. This book is a treatise on the theory of ethics, very popular during the Renaissance. The first line of Lorem Ipsum, \"Lorem ipsum dolor sit amet..\"",
"created": "1329493435",
"genre": "rap",
"updated": "1384306306",
"twitter": "tywangsness",
"name": "Justa Test",
"url": "https:\/\/audiomack.com",
"facebook": "",
"hometown": "Moorhead"
},
"updated": "1384308009",
"featuring": "",
"stream_only": "no",
"image": "https:\/\/assets.dev.audiomack.com\/justa-test\/d6f69aed1e71c67ae012d4e20665d7fb.jpeg",
"genre": "",
"producer": "",
"description": "Contrary to <a href='#'>popular belief</a>, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. \r\n\r\nRichard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, and going through the cites of the word in classical literature, discovered the undoubtable source. Lorem Ipsum comes from sections 1.10.32 and 1.10.33 of \"de Finibus Bonorum et Malorum\" (The Extremes of Good and Evil) by Cicero, written in 45 BC. \r\n\r\nThis book is a treatise on the theory of ethics, very popular during the Renaissance. The first line of Lorem Ipsum, \"Lorem ipsum dolor sit amet..\"",
"released": "1381525467",
"time_ago": "1 year ago",
"live": true,
"streaming_url": "https:\/\/songs.dev.audiomack.com\/streaming\/justa-test\/last-in-class.mp3?Expires=1417699608&Signature=QElRXTi6J9HUNqhrwF3R3qtb84664-nmPRTRaOILDkb-3o-ifXwCckzQVzcfc4agqYRr3nsWqw~ajkVN4mvQ-KYdQASFCwC1X3mTlYA3-FRx7mTTatDcbFHaMd1qQjsswAZ3Aa82o6DIDSV4HfPGGguGszWFEkO5CiAffyAGlDY_&Key-Pair-Id=APKAIKAIRXBA2H7FXITA",
"streaming_url_timeout": 1417699608
},
{
"id": "56",
"album": "",
"title": "Respect Game Or Expect Flames f. Del The Funky Homosapien",
"buy_link": "",
"type": "song",
"artist": "Casual",
"url_slug": "respect-game-or-expect-flames-f-del-the-funky-homosapien",
"status": "complete",
"uploader": {
"id": "17",
"name": "Macli",
"url_slug": "macli",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/82629541ba67f5819b529e33bec0421d.jpeg",
"hometown": "Brooklyn",
"bio": "This is my bio...",
"twitter": "djboothceo",
"facebook": "http:\/\/www.facebook.com\/djboothnet",
"label": "Serious",
"url": "http:\/\/www.djbooth.net",
"genre": "electronic",
"verified": "",
"created": "1331147520",
"updated": "1384287595"
},
"updated": "1373625916",
"featuring": "",
"stream_only": "",
"uploaded": "1345654548",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/36b791b59a4152d96268c65b63fb0097.jpeg",
"genre": "",
"producer": "",
"description": "",
"released": "1345654548",
"time_ago": "2 years ago",
"live": true,
"streaming_url": "https:\/\/songs.dev.audiomack.com\/streaming\/macli\/respect-game-or-expect-flames-f-del-the-funky-homosapien.mp3?Expires=1417699608&Signature=FjsY~gBPtpB8XD1RVuCVpOR2hRNuscQBYUKmuQmbvRoutqq9zDk0Syi4bmfdV7OnpWj2anjbG~Mcl~4Fkxg~Ss4PCBGRxd5qmYHRZZn2UhvfkJkhdD5ut7AwtHPOXceGA-xEIok~Lbp20hiPZOtdOVEj8p6j0fcyv5p~zuFXHZ4_&Key-Pair-Id=APKAIKAIRXBA2H7FXITA",
"streaming_url_timeout": 1417699608
},
{
"id": "61",
"uploader": {
"id": "17",
"name": "Macli",
"url_slug": "macli",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/82629541ba67f5819b529e33bec0421d.jpeg",
"hometown": "Brooklyn",
"bio": "This is my bio...",
"twitter": "djboothceo",
"facebook": "https:\/\/www.facebook.com\/djboothnet",
"label": "Serious",
"url": "http:\/\/www.djbooth.net",
"genre": "electronic",
"verified": "",
"created": "1331147520",
"updated": "1384287595"
},
"type": "song",
"title": "Stay Here (Cuts by Fortune)",
"url_slug": "stay-here-cuts-by-fortune",
"artist": "Charmingly Ghetto",
"album": "Scotland Yahd",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/26818077c1d5215105b251e732cc0da7.jpeg",
"featuring": "",
"producer": "Cypria",
"description": "",
"uploaded": "1347385766",
"released": "1347385766",
"updated": "1373625916",
"status": "complete",
"genre": "",
"stream_only": "",
"buy_link": "",
"time_ago": "2 years ago",
"live": true,
"streaming_url": "https:\/\/songs.dev.audiomack.com\/streaming\/macli\/stay-here-cuts-by-fortune.mp3?Expires=1417699608&Signature=D7R5Sb1bdAj-SAdYJ9AmG4zIpaHcWhm~V4UliuyfcsiI7Di66Mlc8uQxPslxI2nr8qS1zAlVzVCKcssdcl4fa3PuevR2ihJuLrrjFPhv74PubsbDPvhtrGVaLKctxGRMJO8mxWTP6lYGMWm7haLJz8SUuN1~TaHoje4CM3uKTt8_&Key-Pair-Id=APKAIKAIRXBA2H7FXITA",
"streaming_url_timeout": 1417699608
},
{
"id": "72",
"uploader": {
"id": "17",
"name": "Macli",
"url_slug": "macli",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/82629541ba67f5819b529e33bec0421d.jpeg",
"hometown": "Brooklyn",
"bio": "This is my bio...",
"twitter": "djboothceo",
"facebook": "https:\/\/www.facebook.com\/djboothnet",
"label": "Serious",
"url": "http:\/\/www.djbooth.net",
"genre": "electronic",
"verified": "",
"created": "1331147520",
"updated": "1384287595"
},
"type": "song",
"title": "Take Me Back BROOO",
"url_slug": "take-me-back-brooo",
"artist": "Pac Div MY DUDE",
"album": "hey album",
"image": "https:\/\/assets.dev.audiomack.com\/macli\/8d0b34e2078221c64d73613853ea8929.png",
"featuring": "jo momma",
"producer": "Producerrrrr",
"description": "YUPPPPP",
"uploaded": "1351620947",
"released": "1351620947",
"updated": "1374600113",
"status": "complete",
"genre": "",
"stream_only": "yes",
"buy_link": "",
"time_ago": "2 years ago",
"live": true,
"streaming_url": "https:\/\/songs.dev.audiomack.com\/streaming\/macli\/take-me-back-brooo.mp3?Expires=1417699608&Signature=jEy6PYMskymWtl2roKf7Z8QOT-ewxfoTvZjq2h7MseWmDUobqyftKN056GSVDsVKyQPQECtipRE4MXjYSfHYnxiPIPx~YbsAQFE3rI~bQfUwQqihKs0QnxoYFuIz1Q8W-T5Kg~0hHSC-DpNvK5SqPHJeMZnaAk3YiOUANQnShVA_&Key-Pair-Id=APKAIKAIRXBA2H7FXITA",
"streaming_url_timeout": 1417699608
}
]
}
}
Playlist wasn't found:
{
"errorcode": 1016,
"message": "Playlist was not found"
}
Favorite / unfavorite a playlist
Favoriting or unfavoriting requires a valid access token to be sent as part of the request.
PUT /v1/playlist/:id/favorite
DELETE /v1/playlist/:id/favorite
Example response:
A successful favorite or unfavorite returns HTTP Status code 204 (No Content)
Metrics
Get metrics grouped by event type for the playlist object, for events happened within last 60 minutes.
GET /v1/playlist/:id/metrics
Response, JSON object wrapped in results
:
event_counters
- object with counters where attribute is "event_type" string and value is "count"
Response example:
{
"results":
{
"event_counters":
{
"play": 345,
"favorite": 15
}
}
}
Users
User Details
This retrieves the details of the currently authenticated user, and therefore a valid access token must be sent as part of the request.
GET /v1/user
Example successful response:
{
"id": "46",
"name": "Glen Mark Scott",
"url_slug": "glen-scott",
"image": "https:\/\/assets.dev.audiomack.com\/default-artist-image.png",
"hometown": "",
"bio": "Bio - edited",
"twitter": "glenscott",
"facebook": "https:\/\/facebook.com\/glen.scott.716",
"instagram": "glenscott",
"label": "",
"url": "",
"genre": "electronic",
"verified": "",
"updated": "1426519369",
"created": "1409298867",
"status": "active",
"video_ads": "yes",
"follow_download": "yes",
"favorite_music": [
"91",
"61",
"260",
"166",
"163",
"90",
"115",
"161",
"58"
],
"favorite_playlists": [
],
"playlists": [
"51",
"50",
"49",
"48",
"47",
"46",
"45",
"44",
"43",
"42",
"41",
"40",
"39",
"38",
"37",
"36",
"35",
"34",
"33",
"32",
"31",
"30",
"29",
"28",
"27",
"22",
"21",
"20",
"19",
"18",
"16",
"15",
"14",
"13",
"12",
"11",
"10",
"9",
"8",
"6",
"5",
"4",
"3",
"2",
"1"
],
"following": [
"5",
"17",
"4"
],
new_feed_items: 0
}
Registration
POST /v1/user/register
Parameters:
email
artist_name
password
password2
- confirming the password
On successful creation, a 201 Created response is returned. In the body of the response will be an access token that will allow access to endpoints that require authentication. The body will also contain the user's screen name and URL slug.
{
"oauth_token": "87847348738c8f23467a68e5ce33a4db",
"oauth_token_secret": "bf421dd7827058d52ce0666c07852c18",
"user": {
"screen_name": "In The Pines",
"url_slug": "in-the-pines-3"
}
}
A problematic request results in a 422 Unprocessable Entity
response being returned along with details of each problem in a JSON structure.
{
"message": "Validation failed",
"errors": {
"_empty_": {
"email": {
"isEmpty": "This field is required"
},
"password": {
"isEmpty": "Value is required and can't be empty"
},
"password2": {
"isEmpty": "Value is required and can't be empty"
},
"artist_name": {
"isEmpty": "Value is required and can't be empty"
},
"type": {
"isEmpty": "Value is required and can't be empty"
},
"agree_to_terms": {
"isEmpty": "Value is required and can't be empty"
}
}
}
}
Password retrieval
POST /v1/user/forgot-password
This end point allows a user to start the password recovery process. A successful response triggers an e-mail to be sent to the user which contains instructions on how to reset their password. The reset will be done via a browser and not through the application.
Parameters:
email
(required)
Successful response:
HTTP Status 200
Error response:
A problematic request results in a 422 Unprocessable Entity
response being returned along with details of each problem in a JSON structure.
Example 1 - No account for e-mail address:
{
"message": "Validation failed",
"errors": {
"email": {
"keyNotFound": "No account found for this email address 'glennnnnn@glenscott.co.uk'"
}
}
}
Example 2 - E-mail address not supplied:
{
"message": "Validation failed",
"errors": {
"email": {
"isEmpty": "This field is required"
}
}
}
User Playlists
This retrieves all playlists assigned to a user, and includes private playlists. Private playlists should ordinarily NOT be shown to any user except the user that created them.
GET /v1/user/playlists
User Favorites
GET /v1/user/favorites
This call returns an array of favorite entities, which may be a combination of songs, albums, album tracks and playlists.
User Feed
GET /v1/user/feed
User Uploads
GET /v1/user/uploads
User Notifications
Endpoints for work with notifications (for activities) generated by the system for the user. Include activities related to: users following, music repost, adding music as a favorite or into a playlist. More activity types can be added in the future.
Get Notifications List
GET /v1/user/native-notifications
Return list of notifications (activities) for the user. Activities ordered by descending creation date/time, so latest items always returned first. Pagination for this endpoint implemented in the streaming form. Subsequent notification pages can be requested with "paging_token" parameter.
Request parameters:
only_unseen
- boolean, if "true" returns only unseen activities, "false" all activities (default is "false")limit
- integer, max count of activities returned per page (default 20)paging_token
- string, if provided used to retrieve activities from next "page"mark_read
- boolean, if "true" all returned activities will be marked as read, "false" prevents this update (default is "true")
Response, JSON object with:
results
- list of activitiescounters
- current counters for entire feed, contains: total, unseen, unreadpaging_token
- token to be used for the next request to move further down the feed stream (or move to next page)
Response example:
{
"results": [ ... ],
"counters": {
"total": 256,
"unseen": 12,
"unread": 12
}
"paging_token": "asdf1234..."
}
Response headers:
Link
- provide link for the next page, this link already include "paging_token" parameter
Example:
Link: <https://api-domain/v1/native-notifications/?paging_token=asdf1234...>; rel="next"
Each "activity" object returned in "results" list consists of the following fields:
uid
- unique activity ID (string)created_at_unitime
- activity timestamp (integer)created_at_iso8601
- activity timestamp in ISO8601 format (string)actor
- artist performed an activity (object)verb
- type of the activity (string)object
- optional, object of the activity (object)target
- optional, target of the activity (object)seen
- flag showing if it was seen (boolean)read
- flag showing if it was read (boolean)
List of currently supported values for activity "verb", with comments regarding optional fields. Word "current" below refers to the currently logged in user, or feed owner.
follow
- "actor" followed "current": no extra fieldsfavorite
- "actor" added "current's" music to favorites: "object" is a music objectreup
- "actor" reuploaded "current's" music: "object" is a music objectplaylisted
- "actor" added "current's" music into the playlist: "object" is a music object, "target" is a playlist objectplaylistfavorite
- "actor" added "current's" playlist as a favorite: "object" is a playlist objectplaylist_updated
- "actor" added new music into playlist: "object" is a playlist object, "target" is a music object
Mark Notifications as Seen
POST /v1/user/native-notifications/seen
Mark activities as seen. Can do it for a subset of activities, or all unseen activities.
Request parameters: none.
Request body parameters:
uids
- list of activities UIDs to be marked as seenfor_all
- boolean, if "true" operation is performed for all unseen activities, in this case "uids" parameter is ignored; default is "false"
Request example:
{
"uids": [ "abcd1234...", "qwer0987..." ],
"for_all": false
}
Response: 200 OK
empty body
Get Aggregations List
GET /v1/user/native-notifications/aggregations
Return list of aggregations for the user notifications feed. Aggregations ordered by descending creation date/time, so latest items always returned first.
For aggregations that contain a single activity only, this activity object is returned enclosed. For aggregation with more than one activity, clients need to use "GET /v1/user/native-notifications/aggregations/{:aggregate_id}/activities" endpoint to fetch full activities list.
Request parameters:
limit
- integer, max count of aggregations returned per page (default 20)paging_token
- string, if provided used to retrieve activities from next "page"
Response, JSON object with:
results
- list of aggregations; each aggregation can containactivities
attribute - list of activities that belong to this aggregationcounters
- current counters for entire feed, contains: total, unseen, unreadpaging_token
- token to be used for the next request to move further down the feed stream (or move to next page)
Response example:
{
"results": [ ... ],
"counters": {
"total": 256,
"unseen": 12,
"unread": 12
}
"paging_token": "asdf1234..."
}
Response headers:
Link
- provide link for the next page, this link already include "paging_token" parameter
Get Activities for an Aggregation
GET /v1/user/native-notifications/aggregations/{:aggregate_id}/activities
Return list of notifications (activities) that belong to a specific aggregation.
Request parameters:
aggregate_id
- aggregation identifierlimit
- integer, max count of activities returned per page (default 20)paging_token
- string, if provided used to retrieve activities from next "page"
Response, JSON object with:
results
- list of activitiespaging_token
- token to be used for the next request to move further down the feed stream (or move to next page)
Response example:
{
"results": [ ... ],
"paging_token": "asdf1234..."
}
Response headers:
Link
- provide link for the next page, this link already include "paging_token" parameter
Artist Pinned Contents
Endpoints for work with pinned contents for an artist. Contents include: albums, songs, playlists. Total count is limited to 4 for an artist. User id will be retrieved from the access token all the below requests.
Get List
This is the entry and will be returned for any requests, including guest user.
GET /v1/artist/{artist_slug}/pinned
Response body is json like below.
{
[
{
"kind": "song",
"id": 12,
"position": 1,
...
},
{
"kind": "album",
"id": 112,
"position": 2
...
},
]
}
Add New Items to List
This request is only allowed for the logged in artist himself.
POST /v1/artist/{artist_slug}/pinned
This call will add one or multiple items for the user.
Request body is json like below.
{
[
{
"kind": "song",
"id": 12,
"position": 1,
...
},
{
"kind": "album",
"id": 112,
"position": 2
...
},
]
}
Update List with New Items
This request is only allowed for the logged in artist himself.
PUT /v1/artist/{artist_slug}/pinned
This call will remove the existing items for the user. And add the new items from the post body. If you pass in an empty array in the body, all pinned contents will be cleared for the user.
Request body is json like below.
{
[
{
"kind": "playlist",
"id": 120,
"position": 1,
...
},
{
"kind": "album",
"id": 112,
"position": 2
...
},
]
}
Remove Items from List
This request is only allowed for the logged in artist himself.
DELETE /v1/artist/{artist_slug}/pinned
This call will remove the existing items for the user based on the request body.
Request body is json like below.
{
[
{
"kind": "playlist",
"id": 120,
"position": 1,
...
},
{
"kind": "album",
"id": 112,
"position": 2
...
},
]
}
Change Log
- 28th June 2018
- Added ability to add multiple songs to a new playlist on creation, and an existing playlist
- 15th October 2018
- Added artist pinned contents.