10.3 Resources: playlists

Sets are internally called playlists due to naming restrictions and will therefore be named thereafter in the rest of this document.

It’s only possible to read, create and update playlists. Deleting will be implemented shortly.

GET /playlists

Type: Collection of Sets

Collection of all sets.

Parameters

Unauthenticated request:

$ curl 'http://api.soundcloud.com/playlists'

<playlists type="array">
  <playlist>
    <created-at type="datetime">2008-07-22T13:28:59+02:00</created-at>
    <description/>
    <genre/>
    <id type="integer">315</id>
    ...
    <duration>538320</duration>
  </playlist>
</playlists>

Authenticated request:

Generates the same response but the sets returned only contain the tracks that the authenticated user has the right to access.

The collection is searchable by passing the query to the resource. It then lists a subset matching the search query.

$ curl 'http://api.soundcloud.com/playlists?q=ice'

< HTTP/1.1 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<playlists type="array">
  <playlist>
    <created-at type="datetime">2008-07-22T13:28:59+02:00</created-at>
    <description/>
    <genre/>
    <id type="integer">315</id>
    ...
    <duration>538320</duration>
  </playlist>
</playlists>

POST /playlists

Result type: Set

Parameters

Create a set. Tracks need to be uploaded separately and attached to the playlist.

$ curl -u joey:hairspray -X POST 'http://api.soundcloud.com/playlists/' -H 'Content-Type: application/xml'  -d '
  <playlist>
    <created-at type="datetime">2008-07-22T13:28:59+02:00</created-at>
    <title>My Set</title>
    <description>This is my set</description>
    <shared-to>
      <emails type="array">
        <email>
          <address>a.user@example.com</address>
        </email>
      </emails>
    </shared-to>
    <tracks type="array">
      <track>
        <id>14</id>
      </track>
    </tracks>
  </playlist>'

< HTTP/1.1 201 Created

To attach artwork to the playlist to post with a ‘multipart/form-data’ request, hence we can’t send data in XML-format.

$ curl -u joey:hairspray 'http://api.sandbox-soundcloud.com/playlists' \
  -F 'playlist[title]=This is my set' \
  -F playlist[artwork_data]=@the_set_artwork.png

< HTTP/1.1 201 Created
< Location: http://api.soundcloud.com/tracks/14

GET /playlists/{playlist_id}

Result type: Set

Retrieves the given set.

$ curl 'http://api.soundcloud.com/playlists/315'

< HTTP/1.1 200 OK

<playlist>
  <created-at type="datetime">2008-07-22T13:28:59+02:00</created-at>
  <description/>
  <genre/>
  <id type="integer">315</id>
  ...
  <duration>538320</duration>
  <tracks type="array">
    <track>
      <id>12</id>
      ...
    </track>
    <track>
      <id>13</id>
      ...
    </track>
    <track>
      <id>14</id>
      ...
    </track>
  </track>
</playlist>

PUT /playlist/{playlist_id}

Updates the given playlist.

Parameters

The example below updates the playlist with a new title and reorders the tracks from the GET /playlists/{playlist_id} example.

$ curl 'http://api.soundcloud.com/playlists/315' -X PUT -H 'Content-Type: application/xml'  -d '
<playlist>
  <title>Best of Bach</title>
  <shared-to>
    <emails  type="array">
      <email>
        <address>a.user@example.com</address>
      </email>
    </emails>
  </shared-to>
  <tracks type="array">
    <track>
      <id>14</id>
    </track>
    <track>
      <id>13</id>
    </track>
    <track>
      <id>12</id>
    </track>
  </track>
</playlist>
'