NAV
shell ruby python

Introduction

Welcome to the Fanburst API!

All API requests must be made over HTTPS. Requests made over plain HTTP will fail.

We reccomend you pass an Accept-Version header with all of your requests

curl -H "Accept-Version:v1" https://api.fanburst.com/users/52r8yj

Authentication


  Ruby Oauth example

  require 'oauth2'

  client_id     = 'YOUR_CLIENT_ID'
  client_secret = 'YOUR_CLIENT_SECRET'
  redirect_uri  = 'YOUR_REDIRECT_URI'
  site          = "https://fanburst.com"

  client = OAuth2::Client.new(client_id, client_secret, :site => site)

  if params[:code].blank?
    redirect_to client.auth_code.authorize_url(:redirect_uri => redirect_uri)
  else
    token = client.auth_code.get_token(params[:code], :redirect_uri => redirect_uri)
    @access_token = token.token
    @fanburst_user_id = oauth_token.params[:user_id]
    #SAVE THE ACCESS TOKEN AND USER ID TO YOUR DATABASE
  end

Fanburst uses Oauth2 to allow access to the API.

Fanburst expects the client ID to be included in all API requests. Authenticated requests must include a valid access token.

Pagination


  Pagination data is returned in the response headers:

  X-Total: 42
  X-Total-Pages: 5
  X-Page: 3
  X-Per-Page: 10
  X-Next-Page: 4
  X-Prev-Page: 2
  X-Offset: 10

All API endpoints that return multiple items support pagination.

By default we return the first 20 results. To request more results or the next page of results just append one of the parameters below:

HTTP Request

GET https://api.fanburst.com/users/52r8yj/tracks?page=2&per_page=3;

Pagination parameters

Parameter Required Description
page false your current page (default: 1)
per_page false how many to display in a page (default: 10)
offset false the offset to start from (default: 0)

Users

Get User

Example User response:

GET https://api.fanburst.com/users/52r8yj
{ "id": "52r8yj", "name": "Vasta", "permalink": "vasta", "url": "https://fanburst.com/vasta", "avatar_url": "https://img-fanburst.global.ssl.fastly.net/cAGb-85CWfFWOsVQjGMC9_tHIhA=/500x500/10.106.185.136/avatar/92f072ef-8d06-49db-91d5-c29a9dcfe3d9.png", "location": "East Side", "followers_count": 15, "followings_count": 17, "track_count": 5 }

Get a single user by user_id

HTTP Request

GET https://api.fanburst.com/users/<user_id>

Query Parameters

Parameter Required Description
user_id true The ID of the user you are requesting

Properties

Name Example Notes
id "52r8yj" String
name "Vasta" String
permalink "vasta" String
url "https://fanburst.com/vasta" String
avatar_url "https://img-fanburst.global.ssl.fastly.net/cAGb-85CWfFWOsVQjGMC9_tHIhA=/500x500/10.106.185.136/avatar/92f072ef-8d06-49db-91d5-c29a9dcfe3d9.png" String
location "East Side" String
followers_count 8 Integer
followings_count 6 Integer

Get User's tracks

Example tracks response:

GET https://api.fanburst.com/users/52r8yj/tracks
[ { "id": "dw0e49", "title": "The Chainsmokers - Let You Go (Vasta Remix)", "permalink": "the-chainsmokers-let-you-go-vasta-remix", "duration": 292, "url": "https://fanburst.com/vasta/the-chainsmokers-let-you-go-vasta-remix", "published_at": "2015-08-26T15:58:21.000Z", "private": false, "downloadable": false, "images": { "square_150": "https://img-fanburst.global.ssl.fastly.net/Yx8Ko_Ww33bmWxGGlTdh8qQHNlY=/150x150/10.106.185.136/artwork/71b2c46d-7cf3-4d47-929a-cb05523587cb.jpg", "square_250": "https://img-fanburst.global.ssl.fastly.net/l8CR4qXvOBiPH6-lRKPPjkd0AL4=/250x250/10.106.185.136/artwork/71b2c46d-7cf3-4d47-929a-cb05523587cb.jpg", "square_500": "https://img-fanburst.global.ssl.fastly.net/93wMopboEXZ7WUHZh-ipT1OMR44=/500x500/10.106.185.136/artwork/71b2c46d-7cf3-4d47-929a-cb05523587cb.jpg" }, "stream_url": "https://api.fanburst.com/tracks/dw0e49/stream", "user": { "id": "52r8yj", "name": "Vasta", "permalink": "vasta", "url": "https://fanburst.com/vasta", "avatar_url": "https://img-fanburst.global.ssl.fastly.net/cAGb-85CWfFWOsVQjGMC9_tHIhA=/500x500/10.106.185.136/avatar/92f072ef-8d06-49db-91d5-c29a9dcfe3d9.png", "location": "East Side" } }, { "id": "jwy82x", "title": "XYLØ - America (Vasta Remix)", "permalink": "xylo-america-vasta-remix", "duration": 334, "url": "https://fanburst.com/vasta/xylo-america-vasta-remix", "published_at": "2015-08-26T15:58:21.000Z", "private": false, "downloadable": false, "images": { "square_150": "https://img-fanburst.global.ssl.fastly.net/fLu8meZPBNjprENjVYB5SvwJt4Q=/150x150/10.106.185.136/artwork/1d2af852-c002-47c3-9097-81b41e479153.jpg", "square_250": "https://img-fanburst.global.ssl.fastly.net/4n4bCTZjHLy8rHV9afgA2Ocmx8s=/250x250/10.106.185.136/artwork/1d2af852-c002-47c3-9097-81b41e479153.jpg", "square_500": "https://img-fanburst.global.ssl.fastly.net/Ey1HLTjdPjNL5MoaDsxBvEoe2Rc=/500x500/10.106.185.136/artwork/1d2af852-c002-47c3-9097-81b41e479153.jpg" }, "stream_url": "https://api.fanburst.com/tracks/jwy82x/stream", "user": { "id": "52r8yj", "name": "Vasta", "permalink": "vasta", "url": "https://fanburst.com/vasta", "avatar_url": "https://img-fanburst.global.ssl.fastly.net/cAGb-85CWfFWOsVQjGMC9_tHIhA=/500x500/10.106.185.136/avatar/92f072ef-8d06-49db-91d5-c29a9dcfe3d9.png", "location": "East Side" } } ]

Get a users public tracks

HTTP Request

GET https://api.fanburst.com/users/<user_id>/tracks

Query Parameters

Parameter Required Description
user_id true The ID of the user you are requesting

Search Users

Example search response:

GET https://api.fanburst.com/users/search?query=Vasta
{ "id": "52r8yj", "name": "Vasta", "permalink": "vasta", "url": "https://fanburst.com/vasta", "avatar_url": "https://img-fanburst.global.ssl.fastly.net/cAGb-85CWfFWOsVQjGMC9_tHIhA=/500x500/10.106.185.136/avatar/92f072ef-8d06-49db-91d5-c29a9dcfe3d9.png", "location": "East Side", "followers_count": 15, "followings_count": 17, "track_count": 5 }

Search all users

HTTP Request

GET https://api.fanburst.com/users/search?query=YOUR_QUERY

Query Parameters

Parameter Required Description
query true Seach query

Tracks

Get Track

Example tracks response:

GET https://api.fanburst.com/tracks/jwy82x
{ "id": "jwy82x", "title": "XYLØ - America (Vasta Remix)", "permalink": "xylo-america-vasta-remix", "duration": 334, "url": "https://fanburst.com/vasta/xylo-america-vasta-remix", "published_at": "2015-08-26T15:58:21.000Z", "private": false, "downloadable": false, "images": { "square_150": "https://img-fanburst.global.ssl.fastly.net/fLu8meZPBNjprENjVYB5SvwJt4Q=/150x150/10.106.185.136/artwork/1d2af852-c002-47c3-9097-81b41e479153.jpg", "square_250": "https://img-fanburst.global.ssl.fastly.net/4n4bCTZjHLy8rHV9afgA2Ocmx8s=/250x250/10.106.185.136/artwork/1d2af852-c002-47c3-9097-81b41e479153.jpg", "square_500": "https://img-fanburst.global.ssl.fastly.net/Ey1HLTjdPjNL5MoaDsxBvEoe2Rc=/500x500/10.106.185.136/artwork/1d2af852-c002-47c3-9097-81b41e479153.jpg" }, "stream_url": "https://api.fanburst.com/tracks/jwy82x/stream", "user": { "id": "52r8yj", "name": "Vasta", "permalink": "vasta", "url": "https://fanburst.com/vasta", "avatar_url": "https://img-fanburst.global.ssl.fastly.net/cAGb-85CWfFWOsVQjGMC9_tHIhA=/500x500/10.106.185.136/avatar/92f072ef-8d06-49db-91d5-c29a9dcfe3d9.png", "location": "East Side" } }

Get a single track

HTTP Request

GET https://api.fanburst.com/tracks/<TRACK_ID>

Query Parameters

Parameter Required Description
track_id true The ID of the track you are requesting

Create Track

Example tracks response:

POST https://api.fanburst.com/tracks?access_token=YOUR_ACCESS_TOKEN
{ "id": "o9mo1x", "title": "My song", "permalink": "my-song", "duration": 279, "url": "https://fanburst.com/chris/my-song", "published_at": "2015-12-02T12:56:00.719Z", "private": true, "downloadable": true, "stream_url": "https://api.fanburst.com/tracks/o9mo1x/stream", "user": { "id": "q2g86w", "name": "Chris Miller", "permalink": "chris", "url": "https://fanburst.com/chris", "location": "Australia" } }

To create a new track just post an audio file and title. We support mp3, m4a, wav, flac and most other audio types. Max file size through the API is 750mb

HTTP Request

POST https://api.fanburst.com/tracks?access_token=YOUR_ACCESS_TOKEN

Query Parameters

Parameter Required Description
title true Track title
audio_file true Audio file
description false Track description
downloadable false Is this track downloadable?
private true Is this track private?

Stream Track

Example stream response:

GET https://api.fanburst.com/tracks/jwy82x/stream?client_id=YOUR_CLIENT_ID
Status:302 Found Location:https://dl-a-82.fanburst.com/?f=7389f62b-f186-4289-9f27-55110e80df85.mp3&m=mp3&df=7389f62b-f186-4289-9f27-55110e80df85.mp3&e=1462280072&s=ba7cb40d3742c13d769c451d35d9183c948f2296

Redirects the user to a signed stream URL.

HTTP Request

GET https://api.fanburst.com/tracks/<TRACK_ID>/stream

Query Parameters

Parameter Required Description
track_id true The ID of the track you are requesting

Search Tracks

Example search response:

GET https://api.fanburst.com/tracks/search?query=Vasta
[ { "id": "dw0e49", "title": "The Chainsmokers - Let You Go (Vasta Remix)", "permalink": "the-chainsmokers-let-you-go-vasta-remix", "duration": 292, "url": "https://fanburst.com/vasta/the-chainsmokers-let-you-go-vasta-remix", "published_at": "2015-08-26T15:58:21.000Z", "private": false, "downloadable": false, "images": { "square_150": "https://img-fanburst.global.ssl.fastly.net/Yx8Ko_Ww33bmWxGGlTdh8qQHNlY=/150x150/10.106.185.136/artwork/71b2c46d-7cf3-4d47-929a-cb05523587cb.jpg", "square_250": "https://img-fanburst.global.ssl.fastly.net/l8CR4qXvOBiPH6-lRKPPjkd0AL4=/250x250/10.106.185.136/artwork/71b2c46d-7cf3-4d47-929a-cb05523587cb.jpg", "square_500": "https://img-fanburst.global.ssl.fastly.net/93wMopboEXZ7WUHZh-ipT1OMR44=/500x500/10.106.185.136/artwork/71b2c46d-7cf3-4d47-929a-cb05523587cb.jpg" }, "stream_url": "https://api.fanburst.com/tracks/dw0e49/stream", "user": { "id": "52r8yj", "name": "Vasta", "permalink": "vasta", "url": "https://fanburst.com/vasta", "avatar_url": "https://img-fanburst.global.ssl.fastly.net/cAGb-85CWfFWOsVQjGMC9_tHIhA=/500x500/10.106.185.136/avatar/92f072ef-8d06-49db-91d5-c29a9dcfe3d9.png", "location": "East Side" } }, { "id": "xv7dkx", "title": "Aaliyah - One In A Million (Vasta Remix)", "permalink": "aaliyah-one-in-a-million-vasta-remix-2", "duration": 292, "url": "https://fanburst.com/vasta/aaliyah-one-in-a-million-vasta-remix-2", "published_at": "2015-10-21T23:28:09.000Z", "private": false, "downloadable": false, "images": { "square_150": "https://img-fanburst.global.ssl.fastly.net/A1H71f3IB9RIJlMDeCiGIUDcFBE=/150x150/10.106.185.136/artwork/4216bed2-3b08-442a-8c57-2a324c49241d.jpg", "square_250": "https://img-fanburst.global.ssl.fastly.net/0f7_BaQ36mi5ChJmCLiKsCIPSjk=/250x250/10.106.185.136/artwork/4216bed2-3b08-442a-8c57-2a324c49241d.jpg", "square_500": "https://img-fanburst.global.ssl.fastly.net/GozxbVYsdVSc-oK_7bWbJaGkyA0=/500x500/10.106.185.136/artwork/4216bed2-3b08-442a-8c57-2a324c49241d.jpg" }, "stream_url": "https://api.fanburst.com/tracks/xv7dkx/stream", "user": { "id": "52r8yj", "name": "Vasta", "permalink": "vasta", "url": "https://fanburst.com/vasta", "avatar_url": "https://img-fanburst.global.ssl.fastly.net/cAGb-85CWfFWOsVQjGMC9_tHIhA=/500x500/10.106.185.136/avatar/92f072ef-8d06-49db-91d5-c29a9dcfe3d9.png", "location": "East Side" } }, { "id": "9nq142", "title": "Exchange (Vasta Remix)", "permalink": "exchange-vasta-remix", "duration": 249, "url": "https://fanburst.com/vasta/exchange-vasta-remix", "published_at": "2016-02-25T22:22:45.000Z", "private": false, "downloadable": false, "images": { "square_150": "https://img-fanburst.global.ssl.fastly.net/ETRL99eQ5mOCwVQgg6CqhZvrbvo=/150x150/10.106.185.136/artwork/25e8fdd6-caed-48bf-b3f8-ba9e4bd32144.png", "square_250": "https://img-fanburst.global.ssl.fastly.net/JsNmyWXWPhTCbLBfv0P8kWDUJJc=/250x250/10.106.185.136/artwork/25e8fdd6-caed-48bf-b3f8-ba9e4bd32144.png", "square_500": "https://img-fanburst.global.ssl.fastly.net/8YV0qBHWi243k0NX4KqgGUxUJDA=/500x500/10.106.185.136/artwork/25e8fdd6-caed-48bf-b3f8-ba9e4bd32144.png" }, "stream_url": "https://api.fanburst.com/tracks/9nq142/stream", "user": { "id": "52r8yj", "name": "Vasta", "permalink": "vasta", "url": "https://fanburst.com/vasta", "avatar_url": "https://img-fanburst.global.ssl.fastly.net/cAGb-85CWfFWOsVQjGMC9_tHIhA=/500x500/10.106.185.136/avatar/92f072ef-8d06-49db-91d5-c29a9dcfe3d9.png", "location": "East Side" } } ]

Search all public tracks

HTTP Request

GET https://api.fanburst.com/tracks/search?query=YOUR_QUERY

Query Parameters

Parameter Required Description
query true Seach query

Me

Current user

Example User response:

GET https://api.fanburst.com/me
{ "id": "52r8yj", "name": "Vasta", "permalink": "vasta", "url": "https://fanburst.com/vasta", "avatar_url": "https://img-fanburst.global.ssl.fastly.net/cAGb-85CWfFWOsVQjGMC9_tHIhA=/500x500/10.106.185.136/avatar/92f072ef-8d06-49db-91d5-c29a9dcfe3d9.png", "location": "East Side", "followers_count": 15, "followings_count": 17, "track_count": 5 }

Get currently authenticated user

HTTP Request

GET https://api.fanburst.com/me?access_token=12345

Properties

Name Example Notes
id "3" String
name "Vasta" String
permalink "vasta" String
url "https://fanburst.com/vasta" String
avatar_url "https://img-fanburst.global.ssl.fastly.net/cAGb-85CWfFWOsVQjGMC9_tHIhA=/500x500/10.106.185.136/avatar/92f072ef-8d06-49db-91d5-c29a9dcfe3d9.png" String
location "East Side" String
followers_count 8 Integer
followings_count 6 Integer

Resources

All resources available under the user endpoint (tracks,albums,favorites etc) are also available under the /me endpoint

Follow user

Example response:

POST https://api.fanburst.com/me/following
STATUS 200

Follow a user from currently authenticated account

HTTP Request

POST https://api.fanburst.com/me/following?access_token=12345

Properties

Name Example Notes
user_id "52r8yj" String

Resources

All resources available under the user endpoint (tracks,albums,favorites etc) are also available under the /me endpoint

Follow check

Example response:

POST https://api.fanburst.com/me/following/contains
{ "user_id": "52r8yj", "follower_id": "9yjoe6", "status": "true" }

Check to see if the currently authenticated user follows another user

HTTP Request

POST https://api.fanburst.com/me/following/contains?access_token=12345

Properties

Name Example Notes
follower_id "9yjoe6" String

Resolve

Resolve content from URL

Example Resolve response:

GET https://api.fanburst.com/resolve?url=https://fanburst.com/vasta/they-back-it-up-vasta-infuze-remix
{ "content_type": "track", "content_id": "xkg82o", "api_url": "https://api.fanburst.com/tracks/xkg82o" }

Resolve allows you to find the content type (track, user, album) and content id from a Fanburst URL. This method does't yet support private tracks or albums.

HTTP Request

GET https://api.fanburst.com/resolve?url=https://fanburst.com/vasta/they-back-it-up-vasta-infuze-remix

Properties

Name Example Notes
content_type "track" String
content_id "xkg82o" String
api_url "https://api.fanburst.com/tracks/xkg82o" String

Errors

The Fanburst API uses the following error codes:

Error Code Meaning
400 Bad Request -- The request was unacceptable, often due to missing a required parameter.
401 Unauthorized -- No valid API client ID provided.
404 Not Found -- The requested item doesn't exist.
429 Too Many Requests -- Too many requests hit the API too quickly.
500, 503 Internal Server Error -- Something went wrong on our end