Audiomack API Documentation

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:

1. The Consumer obtains an unauthorized Request Token.
2. The User authorizes the Request Token.
3. 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 to oob (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 authorized
• oauth_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 Key
• oauth_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

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.

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.

Music

GET /v1/music/:id

GET /v1/music/(song|album)/(artist slug)/(song or album slug)

GET /v1/music/recent

{
	"results":[],
	"count": 23
}

GET /v1/music/(genre)/recent

{
	"results":[],
	"count": 23
}

GET /v1/music/trending

{
	"results":[],
	"count": 23
}

GET /v1/music/(genre)/trending

PATCH /v1/music/(song|album)/(artist slug)/(song or album slug)

POST /v1/music/:id/play

"https:\/\/songs.dev.audiomack.com\/streaming\/curreny\/corvette-doors.mp3?Expires=1412078706&Signature=AqOdPwjhJrbWeAptHiqBcDnf-H9mreYAsRUx88QDoIMnni85L7DmhgKGagOGMbqkazei6lKmhOSW~XNjREl~ggWaz0k6GMC7C4lmasbf0bCdPwpJ25IIVtL8TxEKEEj5L4jhy8CdyAjs6VW31dK3KcchkrrnsDXF6Ghh1SOA7~I_&Key-Pair-Id=APKAIKAIRXBA2H7FXITA"

POST /v1/music/:id/ads

PUT /v1/music/:id/favorite
DELETE /v1/music/:id/favorite

PUT /v1/music/:id/repost
DELETE /v1/music/:id/repost

GET /v1/music/:id/metrics

{
    "results":
    {
        "event_counters":
        {
            "play": 345,
            "repost": 15
        }
    }
}

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 is all. Other options are music (songs & albums), song, album or playlist.

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 object
  • play_counter - plays counter

Response example:

{
    "results":
    {
        "event_counters":
        {
            "play": 345,
            "favorite": 15
        },
        "music_top10":
        [
            {
                "music": { ... },
                "play_counter": 200
            },
            {
                "music": { ... },
                "play_counter": 183
            },
            ...
        ]
    }
}

Chart Tracks

GET /v1/chart/(songs|albums|playlists)/(chart type)

chart type must be one of the following:

1. total
2. daily
3. weekly
4. monthly
5. yearly

Genre-specific chart tracks

GET /v1/(genre)/chart/(songs|albums|playlists)/(chart type)

Search songs, albums & artists

GET /search

Parameters:

• q - the text to search for
• show - (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 of relevance, recent or popular. 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 returned
• limit - (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 and dancehall.
• verified - (optional) to restrict results from verified accounts, set this parameter

Search autosuggest

GET /search_autosuggest

Parameters:

• q - the text to search for

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 requested
• type - either pv to signify details of a song or album have been viewed, or play 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.

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 playlist
• genre - The genre of the playlist. Must be one of the accepted Genre codes -- see below
• private - (optional) "yes" or "no" to indicate whether the playlist is only viewable by the creator. Defaults to no.
• 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 playlist
• genre - The genre of the playlist. Must be one of the accepted Genre codes -- see below
• music_id - (optional) one or more music ID's that make up the playlist. Multiple music ID's should be separated by commas
• private - (optional) "yes" or "no" to indicate whether the playlist is only viewable by the creator. Defaults to no.
• 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
        }
    }
}

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:

1. 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 activities
• counters - current counters for entire feed, contains: total, unseen, unread
• paging_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 fields
• favorite - "actor" added "current's" music to favorites: "object" is a music object
• reup - "actor" reuploaded "current's" music: "object" is a music object
• playlisted - "actor" added "current's" music into the playlist: "object" is a music object, "target" is a playlist object
• playlistfavorite - "actor" added "current's" playlist as a favorite: "object" is a playlist object
• playlist_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 seen
• for_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 contain activities attribute - list of activities that belong to this aggregation
• counters - current counters for entire feed, contains: total, unseen, unread
• paging_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 identifier
• limit - 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 activities
• paging_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
            ...
        },
    ]
}