01 Introduction

Please note that we will continuously upgrade the API but new versions will have backward compatibility.

The API is built with the design principles of REST in mind, exposing resources which can be manipulated using the HTTP methods GET, POST, PUT and DELETE.

If you have questions, comments or suggestions they are very welcome. Join the discussion on our mailing list or, if you wish to keep it private, send an email to api@soundcloud.com.

If you’ve already read this document from top to bottom, you might want to check the list of changes to this document.

Getting Started

Examples throughout this document will mainly be illustrated using cURL. We start by requesting the tracks that are publicly accessible:

Using cURL:

$ curl 'http://api.soundcloud.com/tracks'
< HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<tracks type="array">
  <track>
    <id type="integer">11</id>
    <title>Final Countdown</title>
    ...
    <sharing>public</sharing>
  </track>
  <track>
    <id type="integer">21</id>
    <title>The Musical Offering</title>
    ...
    <sharing>public</sharing>
  </track>
</tracks>

To get all request and response headers do the cURL request in verbose mode using the -v flag.

Simple Use Case – Uploading an audio file

Please not that this example is using HTTP Basic Authentication and only works on our sandbox. For working with the live soundcloud site you need to use OAuth for authentication, please read more at the Authentication page.

This is how to do it on the sandbox:

1. Create a private track, with audio file and meta data
2. List your contacts
3. Give your contacts access to the track

Setup

You need a SoundCloud user account to be able to upload files. Your soundcloud.com account is transfered to the sandbox on a weekly basis, if you can’t access the sandbox please let us know at api@soundcloud.com

Create a private track and upload a file

Create a private track with title, description and asset data.

$ curl -u joey:hairspray 'http://api.sandbox-soundcloud.com/tracks' -F track[asset_data]=@superstitious.aif -F track[title]=Superstitious -F track[description]='A song about people.' -F track[sharing]=private

< HTTP/1.1 201 Created
< Location: http://api.sandbox-soundcloud.com/tracks/12
<?xml version="1.0" encoding="UTF-8"?>
<track>
  <id type="integer">13409</id>
  <uri>http://api.sandbox-soundcloud.com/tracks/12</uri>
  <title>Superstitious</title>
  <permalink-url>http://sandbox-soundcloud.com/joey/superstitious</permalink-url>
  <description>A song about people.</description>
  <sharing>private</sharing>
  ...
</track>

The track’s canonical resource is given in the Location response header and in this case it is “http://api.sandbox-soundcloud.com/tracks/12”.

The track’s id is 12.

List your contacts

$ curl -u joey:hairspray 'http://api.sandbox-soundcloud.com/me/contacts'

< HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<users>
	<user>
		<id type="integer">3</id>
		<username>vice</username>
		...
	</user>
	<user>
		<id type="integer">4</id>
		<username>mchammer</username>
		...
	</user>
</users>

There are two contacts, their user ids are 3 and 4.

Give your contacts access to the track

$ curl -u joey:hairspray 'http://api.sandbox-soundcloud.com/tracks/12/permissions' -X PUT -H 'Content-Type: application/xml' -d '
<permissions>
	<user-id>3</user-id>
	<user-id>4</user-id>
</permissions>
'

Now MC Hammer and Vanilla Ice have access to your new track “Superstitious” and can listen to it.