GET /api/user

Retrieve informations about the signed in user. Fields should be self explanatory, keep your application flexible on parsing this data because new features will be added to plans.

# GET https://audiobox.fm/api/user.xml
----------------------------------
<?xml version="1.0" encoding="UTF-8"?>
<user>
  <bytes_served>11816536</bytes_served>
  <email>test@audiobox.fm</email>
  <play_count>1</play_count>
  <quota>228822035</quota>
  <tracks_count>28</tracks_count>
  <username>demo</username>
  <available_storage>1073741824</available_storage>
  <allowed_formats>aac;mp3;mp2;m4a;m4b;m4r;mp4;3gp;ogg;oga;flac;spx;rm;ram;wav;mpc;mp+;mpp;aiff;aif;aifc;tta</allowed_formats>
  <time_zone>UTC</time_zone>
  <trial_ends_at>2010-02-09 18:16:00 UTC</trial_ends_at>
  <profile>
    <autoplay>false</autoplay>
    <real_name></real_name>
  </profile>
  <plan>
    <feat_api>true</feat_api>
    <feat_cloud_web_player>true</feat_cloud_web_player>
    <feat_dropbox>false</feat_dropbox>
    <feat_gigjunkie>true</feat_gigjunkie>
    <feat_lastfm>true</feat_lastfm>
    <feat_manager>true</feat_manager>
    <feat_multiformat>true</feat_multiformat>
    <feat_social_networks>true</feat_social_networks>
    <feat_youtube_channel>true</feat_youtube_channel>
    <name>free</name>
  </plan>
</user>
  

GET /api/user?get=ATTRIBUTE

Lightweight call that returns a single attribute in text format.
Allowed ATTRIBUTE is bytes_served, email, play_count, quota, tracks_count, username, available_storage, allowed_formats, trial_ends_at, and comet_channel

• bytes_served - number of bytes streamed.
• email - user's email address.
• play_count - how many plays the user performed until now.
• quota - storage used expressed in bytes.
• tracks_count - how many tracks the user stored in the library.
• username - the user's username.
• available_storage - how much total storage the plan allows, in bytes.
• allowed_formats - media formats the user is allowed to upload, semicolon separated.
• trial_ends_at - datetime on which the trial expires

# GET https://audiobox.fm/api/user.xml?get=email
----------------------------------
test@audiobox.fm

# GET https://audiobox.fm/api/user.xml?get=bytes_served
----------------------------------
76751673020

# GET https://audiobox.fm/api/user.xml?get=trial_ends_at
----------------------------------
2010-02-09 18:16:00 UTC

# GET https://audiobox.fm/api/user.xml?get=test
----------------------------------
<?xml version="1.0" encoding="UTF-8"?> 
<error> 
<status>422</status> 
<message>*get* value not recognized.</message> 
</error>
  

GET /api/player/play

Start streaming the first track.

GET /api/player/play?token=TRACK_TOKEN

Start streaming a specific track identified by TRACK_TOKEN. Returns 404 if the track cannot be found.

GET /api/player/pause

Pauses the current playing track. Has no effect if the track isn't playing.

GET /api/player/next

Point to the next track and start streaming. Respects shuffle and repeat values.

GET /api/player/prev

Point to the previous track and start streaming. Respects shuffle and repeat values.

GET /api/player/volume?to=VALUE

Adjust the volume to VALUE. VALUE is a required parameter and must be between 0 and 100.

GET /api/player/search?term=SEARCH_TERM

Scans the current playlist filtering by SEARCH_TERM.

GET /api/player/shuffle?status=SHUFFLE_STATUS

Set the shuffle value. SHUFFLE_STATUS can be either 'on' or 'off'.

# GET https://audiobox.fm/api/player/shuffle?status=on
----------------------------------
# GET https://audiobox.fm/api/player/shuffle?status=off
----------------------------------
  

GET /api/player/repeat?status=REPEAT_STATUS

Set the repeat value. REPEAT_STATUS can be either 'off' or 'playlist'.

# GET https://audiobox.fm/api/player/repeat?status=off
----------------------------------
# GET https://audiobox.fm/api/player/repeat?status=playlist
----------------------------------
  

GET /api/player/switchplaylist?token=PLAYLIST_TOKEN

Change the current playlist to the one specified with PLAYLIST_TOKEN.

GET /api/player/nowplaying

Shows a Track object (xml or json) if the user is listening to a track. Returns 204 if nothing is found. Please refer to the Track object documentation for details about this object.

GET /api/playlists

Lists all playlists in library.
There are different types of playlists, identified by playlist_type:

• music - main playlist, contains all audio files. Cannot be removed.
• trash - special playlist, media files must be moved here prior permanent deletion. Cannot be removed.
• video - YouTube channel playlist. Present only for reference. Cannot be removed.
• offline - special playlist for applications that does syncing. Cannot be removed.
• custom - playlists created by the user.
• smart - special user created playlist, contains logic to auto-update its content. Tracks cannot be added or removed.

# GET https://audiobox.fm/api/playlists.xml
----------------------------------
<?xml version="1.0" encoding="UTF-8"?>
<playlists type="array">
  <playlist>
    <token>b0YhxeKMwwJ2</token>
    <name>Untitled</name>
    <position></position>
    <playlist_type>custom</playlist_type>
    <playlist_tracks_count>0</playlist_tracks_count>
  </playlist>
  <playlist>
    <token>XvRK5Wk6nS4x</token>
    <name>Music</name>
    <position>1</position>
    <playlist_type>audio</playlist_type>
    <playlist_tracks_count>99</playlist_tracks_count>
  </playlist>
  <playlist>
    <token>EaiTtBpbramd</token>
    <name>Recycle Bin</name>
    <position>3</position>
    <playlist_type>trash</playlist_type>
    <playlist_tracks_count>0</playlist_tracks_count>
  </playlist>
  <playlist>
    <token>f5gM3QHtgzty</token>
    <name>YouTube Channel</name>
    <position>4</position>
    <playlist_type>video</playlist_type>
    <playlist_tracks_count>0</playlist_tracks_count>
  </playlist>
  <playlist>
    <token>0WprCipMaiEn</token>
    <name>Offline</name>
    <position>5</position>
    <playlist_type>offline</playlist_type>
    <playlist_tracks_count>0</playlist_tracks_count>
  </playlist>
</playlists>
  

GET /api/playlists/PLAYLIST_TOKEN(?short=true)

Returns all Track objects present in this playlist.
Accepts an extra parameter 'short=true' to save on data traffic.
The stream_url field for Track objects respects the protocol as requested. If you are using HTTPS then this url will be also HTTPS.

Short parameter response values follows:

• tk - token
• t - track title
• d - track duration
• ds - track duration in seconds
• su - stream url
• y - year (0 if not present)
• l - loved status
• pc - play count
• fs - file size
• tn - track number
• dn - disc number
• fn - file name
• al - start album tag
• g - start genre tag
• c - start covers tag
• ar - start artist tag
• n - name

# GET https://audiobox.fm/api/playlists/mytoken.xml
----------------------------------
<?xml version="1.0" encoding="UTF-8"?>
<tracks type="array">
  <track>
    <token>132031ce-4df0-4beb-bf10-01b73b08b411</token>
    <title>Unearthly Kingdom</title>
    <duration>8:30</duration>
    <duration_in_seconds>510</duration_in_seconds>
    <stream_url>https://audiobox.fm/api/tracks/132031ce-4df0-4beb-bf10-01b73b08b411/stream</stream_url>
    <year>2009</year>
    <loved>true</loved>
    <play_count>112</play_count>
    <audio_file_size>20476983</audio_file_size>
    <track_number>7</track_number>
    <disc_number>1</disc_number>
    <file_name>132031ce-4df0-4beb-bf10-01b73b08b411.mp3</file_name>
    <album>
      <token>HSwacjMk</token>
      <name>All Shall Fall</name>
      <covers>
        <l>http://media.audiobox.fm/images/albums/HSwacjMk/l.jpg?1269959372</l>
        <m>http://media.audiobox.fm/images/albums/HSwacjMk/m.jpg?1269959372</m>
        <s>http://media.audiobox.fm/images/albums/HSwacjMk/s.jpg?1269959372</s>
      </covers>
      <artist>
        <token>0jqUpx9Z</token>
        <name>Immortal</name>
      </artist>
    </album>
    <artist>
      <token>0jqUpx9Z</token>
      <name>Immortal</name>
    </artist>
    <genre>
      <token>UMKcK3IN</token>
      <name>Black Metal</name>
    </genre>
  </track>
</tracks>
  

# GET https://audiobox.fm/api/playlists/mytoken.xml?short=true
----------------------------------
<?xml version="1.0" encoding="UTF-8"?>
<tracks type="array">
  <track>
    <tk>132031ce-4df0-4beb-bf10-01b73b08b411</tk>
    <t>Unearthly Kingdom</t>
    <d>8:30</d>
    <ds>510</ds>
    <su>https://audiobox.fm/api/tracks/132031ce-4df0-4beb-bf10-01b73b08b411/stream</su>
    <y>2009</y>
    <l>true</l>
    <pc>112</pc>
    <fs>20476983</fs>
    <tn>7</tn>
    <dn>1</dn>
    <fn>132031ce-4df0-4beb-bf10-01b73b08b411.mp3</fn>
    <al>
      <tk>HSwacjMk</tk>
      <n>All Shall Fall</n>
      <c>
        <l>http://media.audiobox.fm/images/albums/HSwacjMk/l.jpg?1269959372</l>
        <m>http://media.audiobox.fm/images/albums/HSwacjMk/m.jpg?1269959372</m>
        <s>http://media.audiobox.fm/images/albums/HSwacjMk/s.jpg?1269959372</s>
      </c>
      <ar>
        <tk>0jqUpx9Z</tk>
        <n>Immortal</n>
      </ar>
    </al>
    <ar>
      <tk>0jqUpx9Z</tk>
      <n>Immortal</n>
    </ar>
    <g>
      <tk>UMKcK3IN</tk>
      <n>Black Metal</n>
    </g>
  </track>
</tracks>
  

POST /api/playlists

Creates a new custom playlist. You must send a parameter name with your playlist name.

PUT /api/playlists/PLAYLIST_TOKEN

Rename a custom playlists. You must send the parameter name with your value.

DELETE /api/playlists/PLAYLIST_TOKEN

Destroys a custom playlist. You cannot destroy all types of playlist. Refer to the types above described in /api/playlists endpoint.

PUT /api/playlists/empty_trash

Permanently deletes every track in trash playlist. This operation cannot be reverted.

PUT /api/playlist/PLAYLIST_TOKEN/add_tracks

Add an array of Tracks identified by the parameter 'track_tokens'.
Not every playlist is injectable, for instance you cannot add tracks to a Music, Smart, Video playlists.
Accepts also a single track.

# PUT https://audiobox.fm/api/playlists/mytoken/add_tracks?track_tokens[]=track1_token&track_tokens[]=track2_token
----------------------------------
# PUT https://audiobox.fm/api/playlists/mytoken/add_tracks?track_tokens=track1_token
----------------------------------
  

PUT /api/playlist/PLAYLIST_TOKEN/remove_tracks

Removes an array of Tracks identified by the parameter 'track_tokens'. Moving a track out of his playlist have diverse effects, based on the requested playlist.
For example:

• remove a track from the Music playlist: will be moved in the Trash playlist, if the track is present in other playlists, such as custom ones, it will be unlinked aswell.
• remove a track from the Trash playlist: will be moved back in the Music playlist (to permanently delete tracks check the empty_trash endpoint).

# PUT https://audiobox.fm/api/playlists/mytoken/remove_tracks?track_tokens[]=track1_token&track_tokens[]=track2_token
----------------------------------
# PUT https://audiobox.fm/api/playlists/mytoken/remove_tracks?track_tokens=track1_token
----------------------------------
  

GET /api/tracks

Get a list of MD5 hashes of the stored tracks. Duplicates are stripped (they just appear once).
This is useful when building a desktop synchronization tool, you may want to check a list of remote hashes against a local one to identify which files have been already uploaded.
To save space the response is a text with values separated by a semicolon.

# GET https://audiobox.fm/api/tracks
----------------------------------
dcc44d6c5b37a4e98326e099c2672ce1;4eed8c08fa7c29ae702f85a0dcfd2c6f
  

GET /api/tracks/TRACK_TOKEN_OR_MD5_HASH(?short=true)

Get informations about a track. Lookup can be done via a token or directly via a MD5 hash. In case of multiple hashes matching, the first result is returned. Returns 204 if the track exists but it's still in processing phase or 404 if not found.
Accepts an extra parameter 'short=true' to save on data traffic.
The TRACK_TOKEN parameter is obtainable by querying a Playlist. It is also returned when uploading a file.
The stream_url field protocol prefix changes based on the current request.

# GET /api/tracks/OtALYHVEIKQ5XM4DUXixel.xml
----------------------------------
<?xml version="1.0" encoding="UTF-8"?>
<track>
  <token>5985775a-f1bf-4985-a688-b0034beab265</token>
  <title>A Witch Is Born</title>
  <duration>4:21</duration>
  <duration_in_seconds>261</duration_in_seconds>
  <stream_url>https://audiobox.fm/api/tracks/5985775a-f1bf-4985-a688-b0034beab265/stream</stream_url>
  <year>1995</year>
  <loved>false</loved>
  <play_count>10</play_count>
  <audio_file_size>8512992</audio_file_size>
  <track_number>4</track_number>
  <disc_number>1</disc_number>
  <file_name>5985775a-f1bf-4985-a688-b0034beab265.mp3</file_name>
  <album>
    <token>2ATnrgEs</token>
    <name>Seen Through The Veils Of Darkness (The Second Spell)</name>
    <covers>
      <l>http://media.audiobox.fm/images/albums/2ATnrgEs/l.jpg?1269962515</l>
      <m>http://media.audiobox.fm/images/albums/2ATnrgEs/m.jpg?1269962515</m>
      <s>http://media.audiobox.fm/images/albums/2ATnrgEs/s.jpg?1269962515</s>
    </covers>
    <artist>
      <token>dvPO97qH</token>
      <name>Gehenna</name>
    </artist>
  </album>
  <artist>
    <token>dvPO97qH</token>
    <name>Gehenna</name>
  </artist>
  <genre>
    <token>UMKcK3IN</token>
    <name>Black Metal</name>
  </genre>
</track>
  

GET /api/tracks/TRACK_TOKEN/stream

If successful redirects with a 303 HTTP status (See Other) to the computed and private HTTP streaming URL.
It is entirely possible that the redirect URL will be http, so if you are calling AudioBox.fm API through SSL be ready for that.
When you call this action the system will send a now playing notification to both our systems and Last.fm if the user enabled the related AudioMash.

GET /api/tracks/TRACK_TOKEN/download

Same effect as stream but it doesn't fire the various now playing notifications. Useful for syncing processes.

POST /api/tracks

Uploads a media file. See the Appendix A for a cURL example. This will set the track source as 'api'.
Remember the examine the response body for this call, as this will contain the track token you need to keep track of this particular upload.
Uploads are queued, therefore the media file might not be immediately available as it has to be parsed by our system.
Check the next endpoint for more informations. In order to perform a track upload you need to supply a parameter containing the binary data stream, called either "media" or "file".

POST /api/tracks/TRACK_TOKEN/scrobble

Records that a track has been played.
When you call this action the system will send a scrobble notification to both our systems and Last.fm if the user enabled the related AudioMash.
This action is rate-limited, use it following the Last.fm conventions "3.1 When to Submit".

PUT /api/tracks/TRACK_TOKEN/love

Flags a track as loved. Returns the track.

PUT /api/tracks/TRACK_TOKEN/unlove

Removes the loved flag from the track. Returns the track.