SoundCloud for Developers

Discover, connect and build

HTTP API Reference

The SoundCloud API exposes SoundCloud resources like sounds, sets and users. These resources can be accessed and manipulated using the HTTP methods GET, POST, PUT and DELETE.

All SoundCloud resources are accessed and manipulated in a similar way. A list of the latest resource is usually available through /[resource name], a single specific resource through /[resource name][id] and related subresources like a tracks comments through /[resource name]/[id]/[subresource name].

Resources are returned as XML by default, or JSON if a .json extension is appended to the resource URI. We encourage you to use JSON. You can also send an appropriate Accept header specifying the format you would like. For example, a request with the header Accept: application/json will return resources represented as a JSON document.

Unless otherwise specified, the base URL for API endpoints is:

https://api.soundcloud.com

To access public resources you just have to pass a client_id parameter:

$ curl https://api.soundcloud.com/tracks?client_id=YOUR_CLIENT_ID

To act on behalf of a SoundCloud user, they must first authenticate your app.

/connect

Full URI: https://soundcloud.com/connect

The OAuth2 authorization endpoint. Your app redirects a user to this endpoint, allowing them to delegate access to their account.

Parameters

Parameter Type Description
client_id string The client id belonging to your application
redirect_uri string The redirect uri you have configured for your application
response_type enumeration (code, token_and_code)
scope string Must be '*' or 'non-expiring'
display string Can specify a value of 'popup' for mobile optimized screen
state string Any value included here will be appended to the redirect URI

/oauth2/token

The OAuth2 token endpoint. This endpoint accepts POST requests and is used to provision access tokens once a user has authorized your application.

Note All parameters must be sent in the request body, not as part of the query string.

Parameters

Parameter Type Description
client_id string The client id belonging to your application
client_secret string The client secret belonging to your application
redirect_uri string The redirect uri you have configured for your application
grant_type enumeration (authorization_code, refresh_token, password, client_credentials, oauth1_token)
code string The authorization code obtained when user is sent to redirect_uri

Example

$ curl -X POST "https://api.soundcloud.com/oauth2/token" \\
           -F 'client_id=YOUR_CLIENT_ID' \\
           -F 'client_secret=YOUR_CLIENT_SECRET' \\
           -F 'grant_type=authorization_code' \\
           -F 'redirect_uri=http://yourapp.com/soundcloud/oauth-callback' \\
           -F 'code=0000000EYAA1CRGodSoKJ9WsdhqVQr3g'
{
  "access_token": "04u7h-4cc355-70k3n",
  "scope": "non-expiring"
}

/users

A SoundCloud user

Example

$ curl "http://api.soundcloud.com/users/3207.json?client_id=YOUR_CLIENT_ID"
{
  "id": 3207,
  "permalink": "jwagener",
  "username": "Johannes Wagener",
  "uri": "http://api.soundcloud.com/users/3207",
  "permalink_url": "http://soundcloud.com/jwagener",
  "avatar_url": "http://i1.sndcdn.com/avatars-000001552142-pbw8yd-large.jpg?142a848",
  "country": "Germany",
  "full_name": "Johannes Wagener",
  "city": "Berlin",
  "description": "<b>Hacker at SoundCloud</b>\r\n\r\nSome of my recent Hacks:\r\n\r\nsoundiverse.com \r\nbrowse recordings with the FiRe app by artwork\r\n\r\ntopbillin.com \r\nfind people to follow on SoundCloud\r\n\r\nchatter.fm \r\nget your account hooked up with a voicebox\r\n\r\nrecbutton.com \r\nrecord straight to your soundcloud account",
  "discogs_name": null,
  "myspace_name": null,
  "website": "http://johannes.wagener.cc",
  "website_title": "johannes.wagener.cc",
  "online": true,
  "track_count": 12,
  "playlist_count": 1,
  "followers_count": 417,
  "followings_count": 174,
  "public_favorites_count": 26
}

Properties

name description example value
id integer ID 123
permalink permalink of the resource "sbahn-sounds"
username username "Doctor Wilson"
uri API resource URL http://api.soundcloud.com/comments/32562
permalink_url URL to the SoundCloud.com page "http://soundcloud.com/bryan/sbahn-sounds"
avatar_url URL to a JPEG image "http://i1.sndcdn.com/avatars-000011353294-n0axp1-large.jpg"
country country "Germany"
full_name first and last name "Tom Wilson"
city city "Berlin"
description description "Buskers playing in the S-Bahn station in Berlin"
discogs-name Discogs name "myrandomband"
myspace-name MySpace name "myrandomband"
website a URL to the website "http://facebook.com/myrandomband"
website-title a custom title for the website "myrandomband on Facebook"
online online status (boolean) true
track_count number of public tracks 4
playlist_count number of public playlists 5
followers_count number of followers 54
followings_count number of followed users 75
public_favorites_count number of favorited public tracks 7
avatar_data binary data of user avatar (only for uploading)

Subresources

Methods Path Description
GET /users/{id} a user
GET /users/{id}/tracks list of tracks of the user
GET /users/{id}/playlists list of playlists (sets) of the user
GET /users/{id}/followings list of users who are followed by the user
GET, PUT, DELETE /users/{id}/followings/{id} a user who is followed by the user
GET /users/{id}/followers list of users who are following the user
GET /users/{id}/followers/{id} user who is following the user
GET /users/{id}/comments list of comments from this user
GET /users/{id}/favorites list of tracks favorited by the user
GET, PUT, DELETE /users/{id}/favorites/{id} track favorited by the user
GET /users/{id}/groups list of joined groups
GET, PUT, DELETE /users/{id}/web-profiles list of web profiles

Filters

Parameter Type Description
q string a string to search for (see search documentation)

/tracks

A SoundCloud Track

Example

$ curl "http://api.soundcloud.com/tracks/13158665.json?client_id=YOUR_CLIENT_ID"
{
  "id": 13158665,
  "created_at": "2011/04/06 15:37:43 +0000",
  "user_id": 3699101,
  "duration": 18109,
  "commentable": true,
  "state": "finished",
  "sharing": "public",
  "tag_list": "soundcloud:source=iphone-record",
  "permalink": "munching-at-tiannas-house",
  "description": null,
  "streamable": true,
  "downloadable": true,
  "genre": null,
  "release": null,
  "purchase_url": null,
  "label_id": null,
  "label_name": null,
  "isrc": null,
  "video_url": null,
  "track_type": "recording",
  "key_signature": null,
  "bpm": null,
  "title": "Munching at Tiannas house",
  "release_year": null,
  "release_month": null,
  "release_day": null,
  "original_format": "m4a",
  "original_content_size": 10211857,
  "license": "all-rights-reserved",
  "uri": "http://api.soundcloud.com/tracks/13158665",
  "permalink_url": "http://soundcloud.com/user2835985/munching-at-tiannas-house",
  "artwork_url": null,
  "waveform_url": "http://w1.sndcdn.com/fxguEjG4ax6B_m.png",
  "user": {
    "id": 3699101,
    "permalink": "user2835985",
    "username": "user2835985",
    "uri": "http://api.soundcloud.com/users/3699101",
    "permalink_url": "http://soundcloud.com/user2835985",
    "avatar_url": "http://a1.sndcdn.com/images/default_avatar_large.png?142a848"
  },
  "stream_url": "http://api.soundcloud.com/tracks/13158665/stream",
  "download_url": "http://api.soundcloud.com/tracks/13158665/download",
  "playback_count": 0,
  "download_count": 0,
  "favoritings_count": 0,
  "comment_count": 0,
  "created_with": {
    "id": 124,
    "name": "SoundCloud iPhone",
    "uri": "http://api.soundcloud.com/apps/124",
    "permalink_url": "http://soundcloud.com/apps/iphone"
  },
  "attachments_uri": "http://api.soundcloud.com/tracks/13158665/attachments"
}

Properties

name description example value
id integer ID 123
created_at timestamp of creation "2009/08/13 18:30:10 +0000"
user_id user-id of the owner 343
user mini user representation of the owner {id: 343, username: "Doctor Wilson"...}
title track title "S-Bahn Sounds"
permalink permalink of the resource "sbahn-sounds"
permalink_url URL to the SoundCloud.com page "http://soundcloud.com/bryan/sbahn-sounds"
uri API resource URL "http://api.soundcloud.com/tracks/123"
sharing public/private sharing "public"
embeddable_by who can embed this track or playlist "all", "me", or "none"
purchase_url external purchase link "http://amazon.com/buy/a43aj0b03"
artwork_url URL to a JPEG image "http://i1.sndcdn.com/a....-large.jpg?142a848"

JPEG, PNG and GIF are accepted when uploading and will be encoded to multiple JPEGs in these formats:

  • t500x500: 500×500
  • crop: 400×400
  • t300x300: 300×300
  • large: 100×100 (default)
  • t67x67: 67×67 (only on artworks)
  • badge: 47×47
  • small: 32×32
  • tiny: 20×20 (on artworks)
  • tiny: 18×18 (on avatars)
  • mini: 16×16
  • original: (originally uploaded image)

The URL is pointing to the format large by default. If you want to use a different format you have to replace large with the specific format name in the image URL:

For example:

http://i1.sndcdn.com/avatars-000000011308-xq0whu-large.jpg?b17c165

to

http://i1.sndcdn.com/avatars-000000011308-xq0whu-crop.jpg?b17c165

description HTML description "my first track"
label label mini user object {id:123, username: "BeatLabel"...}
duration duration in milliseconds 1203400
genre genre "HipHop"
shared_to_count number of sharings (if private) 45
tag_list list of tags "tag1 \"hip hop\" geo:lat=32.444 geo:lon=55.33"

The tag_list property contains a list of tags seperated by spaces. Multiword tags are quoted in doublequotes. We also support machine tags that follow the pattern NAMESPACE:KEY=VALUE. For example:

  • geo:lat=43.555
  • camel:size=medium
  • “machine:tag=with space”

Machine tags are not revealed to the user on the track pages.

label_id id of the label user 54677
label_name label name "BeatLabel"
release release number 3234
release_day day of the release 21
release_month month of the release 5
release_year year of the release 2001
streamable streamable via API (boolean) true
downloadable downloadable (boolean) true
state encoding state "finished"

Possible values:

  • “processing”
  • “failed”
  • “finished”
license creative common license "no-rights-reserved"

Possible values:

  • “no-rights-reserved”
  • “all-rights-reserved”
  • “cc-by”
  • “cc-by-nc”
  • “cc-by-nd”
  • “cc-by-sa”
  • “cc-by-nc-nd”
  • “cc-by-nc-sa”
track_type track type "recording"

Possible values:

  • “original”
  • “remix”
  • “live”
  • “recording”
  • “spoken”
  • “podcast”
  • “demo”
  • “in progress”
  • “stem”
  • “loop”
  • “sound effect”
  • “sample”
  • “other”
waveform_url URL to PNG waveform image "http://w1.sndcdn.com/fxguEjG4ax6B_m.png"
download_url URL to original file "http://api.soundcloud.com/tracks/3/download"
stream_url link to 128kbs mp3 stream "http://api.soundcloud.com/tracks/3/stream"
video_url a link to a video page "http://vimeo.com/3302330"
bpm beats per minute 120
commentable track commentable (boolean) true
isrc track ISRC "I123-545454"
key_signature track key "Cmaj"
comment_count track comment count 12
download_count track download count 45
playback_count track play count 435
favoritings_count track favoriting count 6
original_format file format of the original file "aiff"
original_content_size size in bytes of the original file 10211857
created_with the app that the track created {"id"=>3434, "..."=>nil}

This property is only present if the track was created with an app that is published in the app gallery. More details about this are in the /apps docs.

asset_data binary data of the audio file (only for uploading)
artwork_data binary data of the artwork image (only for uploading)
user_favorite track favorite of current user (boolean, authenticated requests only) 1

Subresources

Methods Path Description
GET, PUT, DELETE /tracks/{id} a track
GET /tracks/{id}/comments comments for the track
GET, PUT, DELETE /tracks/{id}/comments/{comment-id} a comment for the track
GET /tracks/{id}/favoriters users who favorited the track
GET /tracks/{id}/favoriters/{user-id} a user who has favorited to the track
GET, POST, PUT, DELETE /tracks/{id}/shared-to/users users who have access to the track
GET, POST, PUT, DELETE /tracks/{id}/shared-to/emails email addresses who are invited to the track
GET, PUT /tracks/{id}/secret-token secret token of the track

Filters

Parameter Type Description
q string a string to search for (see search documentation)
tags list a comma separated list of tags
filter enumeration (all,public,private,streamable,downloadable)
license enumeration Filter on license. (see license attribute)
bpm[from] number return tracks with at least this bpm value
bpm[to] number return tracks with at most this bpm value
duration[from] number return tracks with at least this duration (in millis)
duration[to] number return tracks with at most this duration (in millis)
created_at[from] date (yyyy-mm-dd hh:mm:ss) return tracks created at this date or later
created_at[to] date (yyyy-mm-dd hh:mm:ss) return tracks created at this date or earlier
ids list a comma separated list of track ids to filter on
genres list a comma separated list of genres
types enumeration a comma separated list of types

/playlists

A SoundCloud Set is internally called playlists due to some naming restrictions.

Example

$ curl "http://api.soundcloud.com/playlists/405726.json?client_id=YOUR_CLIENT_ID"
{
  "kind": "playlist",
  "id": 405726,
  "created_at": "2010/11/02 09:24:50 +0000",
  "user_id": 3207,
  "duration": 154516,
  "sharing": "public",
  "tag_list": "",
  "permalink": "field-recordings",
  "track_count": 5,
  "streamable": true,
  "downloadable": true,
  "embeddable_by": "me",
  "purchase_url": null,
  "label_id": null,
  "type": "other",
  "playlist_type": "other",
  "ean": "",
  "description": "a couple of field recordings to test http://soundiverse.com.\r\n\r\nrecorded with the fire recorder: http://soundcloud.com/apps/fire",
  "genre": "",
  "release": "",
  "purchase_title": null,
  "label_name": "",
  "title": "Field Recordings",
  "release_year": null,
  "release_month": null,
  "release_day": null,
  "license": "all-rights-reserved",
  "uri": "http://api.soundcloud.com/playlists/405726",
  "permalink_url": "http://soundcloud.com/jwagener/sets/field-recordings",
  "artwork_url": "http://i1.sndcdn.com/artworks-000025801802-1msl1i-large.jpg?5e64f12",
  "user": {
    "id": 3207,
    "kind": "user",
    "permalink": "jwagener",
    "username": "Johannes Wagener",
    "uri": "http://api.soundcloud.com/users/3207",
    "permalink_url": "http://soundcloud.com/jwagener",
    "avatar_url": "http://i1.sndcdn.com/avatars-000014428549-3at7qc-large.jpg?5e64f12"
  },
  "tracks": [
    {
      "kind": "track",
      "id": 6621631,
      "created_at": "2010/11/02 09:08:43 +0000",
      "user_id": 3207,
      "duration": 27099,
      "commentable": true,
      "state": "finished",
      "original_content_size": 2382624,
      "sharing": "public",
      "tag_list": "Fieldrecording geo:lat=52.527544 geo:lon=13.402905",
      "permalink": "coffee-machine",
      "streamable": true,
      "embeddable_by": "all",
      "downloadable": false,
      "purchase_url": null,
      "label_id": null,
      "purchase_title": null,
      "genre": "",
      "title": "coffee machine",
      "description": "",
      "label_name": "",
      "release": "",
      "track_type": "",
      "key_signature": "",
      "isrc": "",
      "video_url": null,
      "bpm": null,
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "http://api.soundcloud.com/tracks/6621631",
      "user": {
        "id": 3207,
        "kind": "user",
        "permalink": "jwagener",
        "username": "Johannes Wagener",
        "uri": "http://api.soundcloud.com/users/3207",
        "permalink_url": "http://soundcloud.com/jwagener",
        "avatar_url": "http://i1.sndcdn.com/avatars-000014428549-3at7qc-large.jpg?5e64f12"
      },
      "created_with": {
        "id": 64,
        "kind": "app",
        "name": "FiRe - Field Recorder",
        "uri": "http://api.soundcloud.com/apps/64",
        "permalink_url": "http://soundcloud.com/apps/fire",
        "external_url": "http://itunes.apple.com/us/app/fire-2-field-recorder/id436241643?mt=8"
      },
      "permalink_url": "http://soundcloud.com/jwagener/coffee-machine",
      "artwork_url": "http://i1.sndcdn.com/artworks-000002863219-4zpxc0-large.jpg?5e64f12",
      "waveform_url": "http://w1.sndcdn.com/Yva1Qimi7TVd_m.png",
      "stream_url": "http://api.soundcloud.com/tracks/6621631/stream",
      "playback_count": 1249,
      "download_count": 114,
      "favoritings_count": 14,
      "comment_count": 11,
      "attachments_uri": "http://api.soundcloud.com/tracks/6621631/attachments"
    },
    {
      "kind": "track",
      "id": 6621549,
      "created_at": "2010/11/02 09:00:23 +0000",
      "user_id": 3207,
      "duration": 65618,
      "commentable": true,
      "state": "finished",
      "original_content_size": 5780256,
      "sharing": "public",
      "tag_list": "Fieldrecording geo:lat=52.528181 geo:lon=13.412658",
      "permalink": "tram-in-berlin",
      "streamable": true,
      "embeddable_by": "all",
      "downloadable": true,
      "purchase_url": null,
      "label_id": null,
      "purchase_title": null,
      "genre": "",
      "title": "tram in berlin",
      "description": "",
      "label_name": "",
      "release": "",
      "track_type": "recording",
      "key_signature": "",
      "isrc": "",
      "video_url": null,
      "bpm": null,
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "http://api.soundcloud.com/tracks/6621549",
      "user": {
        "id": 3207,
        "kind": "user",
        "permalink": "jwagener",
        "username": "Johannes Wagener",
        "uri": "http://api.soundcloud.com/users/3207",
        "permalink_url": "http://soundcloud.com/jwagener",
        "avatar_url": "http://i1.sndcdn.com/avatars-000014428549-3at7qc-large.jpg?5e64f12"
      },
      "created_with": {
        "id": 64,
        "kind": "app",
        "name": "FiRe - Field Recorder",
        "uri": "http://api.soundcloud.com/apps/64",
        "permalink_url": "http://soundcloud.com/apps/fire",
        "external_url": "http://itunes.apple.com/us/app/fire-2-field-recorder/id436241643?mt=8"
      },
      "permalink_url": "http://soundcloud.com/jwagener/tram-in-berlin",
      "artwork_url": "http://i1.sndcdn.com/artworks-000002863163-6f2aqe-large.jpg?5e64f12",
      "waveform_url": "http://w1.sndcdn.com/u04ibjx6FYdM_m.png",
      "stream_url": "http://api.soundcloud.com/tracks/6621549/stream",
      "download_url": "http://api.soundcloud.com/tracks/6621549/download",
      "playback_count": 578,
      "download_count": 93,
      "favoritings_count": 4,
      "comment_count": 3,
      "attachments_uri": "http://api.soundcloud.com/tracks/6621549/attachments"
    },
    {
      "kind": "track",
      "id": 6668072,
      "created_at": "2010/11/03 19:47:11 +0000",
      "user_id": 3207,
      "duration": 21871,
      "commentable": true,
      "state": "finished",
      "original_content_size": 1921800,
      "sharing": "public",
      "tag_list": "geo:lat=52.527529 geo:lon=13.402961",
      "permalink": "alex-playing-drums",
      "streamable": true,
      "embeddable_by": "all",
      "downloadable": true,
      "purchase_url": null,
      "label_id": null,
      "purchase_title": null,
      "genre": null,
      "title": "alex playing drums",
      "description": "",
      "label_name": "",
      "release": "",
      "track_type": "recording",
      "key_signature": "",
      "isrc": "",
      "video_url": null,
      "bpm": null,
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "http://api.soundcloud.com/tracks/6668072",
      "user": {
        "id": 3207,
        "kind": "user",
        "permalink": "jwagener",
        "username": "Johannes Wagener",
        "uri": "http://api.soundcloud.com/users/3207",
        "permalink_url": "http://soundcloud.com/jwagener",
        "avatar_url": "http://i1.sndcdn.com/avatars-000014428549-3at7qc-large.jpg?5e64f12"
      },
      "created_with": {
        "id": 64,
        "kind": "app",
        "name": "FiRe - Field Recorder",
        "uri": "http://api.soundcloud.com/apps/64",
        "permalink_url": "http://soundcloud.com/apps/fire",
        "external_url": "http://itunes.apple.com/us/app/fire-2-field-recorder/id436241643?mt=8"
      },
      "permalink_url": "http://soundcloud.com/jwagener/alex-playing-drums",
      "artwork_url": "http://i1.sndcdn.com/artworks-000002888918-takbu6-large.jpg?5e64f12",
      "waveform_url": "http://w1.sndcdn.com/MQnxWxIH94ai_m.png",
      "stream_url": "http://api.soundcloud.com/tracks/6668072/stream",
      "download_url": "http://api.soundcloud.com/tracks/6668072/download",
      "playback_count": 400,
      "download_count": 84,
      "favoritings_count": 2,
      "comment_count": 1,
      "attachments_uri": "http://api.soundcloud.com/tracks/6668072/attachments"
    },
    {
      "kind": "track",
      "id": 6698933,
      "created_at": "2010/11/04 19:09:32 +0000",
      "user_id": 3207,
      "duration": 12726,
      "commentable": true,
      "state": "finished",
      "original_content_size": 1116936,
      "sharing": "public",
      "tag_list": "geo:lat=52.528450 geo:lon=13.404099",
      "permalink": "typing",
      "streamable": true,
      "embeddable_by": "all",
      "downloadable": false,
      "purchase_url": null,
      "label_id": null,
      "purchase_title": null,
      "genre": null,
      "title": "typing",
      "description": "",
      "label_name": "",
      "release": "",
      "track_type": "recording",
      "key_signature": "",
      "isrc": "",
      "video_url": null,
      "bpm": null,
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "http://api.soundcloud.com/tracks/6698933",
      "user": {
        "id": 3207,
        "kind": "user",
        "permalink": "jwagener",
        "username": "Johannes Wagener",
        "uri": "http://api.soundcloud.com/users/3207",
        "permalink_url": "http://soundcloud.com/jwagener",
        "avatar_url": "http://i1.sndcdn.com/avatars-000014428549-3at7qc-large.jpg?5e64f12"
      },
      "created_with": {
        "id": 64,
        "kind": "app",
        "name": "FiRe - Field Recorder",
        "uri": "http://api.soundcloud.com/apps/64",
        "permalink_url": "http://soundcloud.com/apps/fire",
        "external_url": "http://itunes.apple.com/us/app/fire-2-field-recorder/id436241643?mt=8"
      },
      "permalink_url": "http://soundcloud.com/jwagener/typing",
      "artwork_url": "http://i1.sndcdn.com/artworks-000002903990-le6t7d-large.jpg?5e64f12",
      "waveform_url": "http://w1.sndcdn.com/ZSil4IqhP6Hh_m.png",
      "stream_url": "http://api.soundcloud.com/tracks/6698933/stream",
      "playback_count": 1151,
      "download_count": 102,
      "favoritings_count": 1,
      "comment_count": 0,
      "attachments_uri": "http://api.soundcloud.com/tracks/6698933/attachments"
    },
    {
      "kind": "track",
      "id": 6770077,
      "created_at": "2010/11/07 02:45:11 +0000",
      "user_id": 3207,
      "duration": 27202,
      "commentable": true,
      "state": "finished",
      "original_content_size": 2392840,
      "sharing": "public",
      "tag_list": "geo:lat=52.531203 geo:lon=13.412165",
      "permalink": "bassy",
      "streamable": true,
      "embeddable_by": "all",
      "downloadable": true,
      "purchase_url": null,
      "label_id": null,
      "purchase_title": null,
      "genre": "",
      "title": "bassy",
      "description": "",
      "label_name": "",
      "release": "",
      "track_type": "recording",
      "key_signature": "",
      "isrc": "",
      "video_url": null,
      "bpm": null,
      "release_year": null,
      "release_month": null,
      "release_day": null,
      "original_format": "wav",
      "license": "cc-by",
      "uri": "http://api.soundcloud.com/tracks/6770077",
      "user": {
        "id": 3207,
        "kind": "user",
        "permalink": "jwagener",
        "username": "Johannes Wagener",
        "uri": "http://api.soundcloud.com/users/3207",
        "permalink_url": "http://soundcloud.com/jwagener",
        "avatar_url": "http://i1.sndcdn.com/avatars-000014428549-3at7qc-large.jpg?5e64f12"
      },
      "created_with": {
        "id": 64,
        "kind": "app",
        "name": "FiRe - Field Recorder",
        "uri": "http://api.soundcloud.com/apps/64",
        "permalink_url": "http://soundcloud.com/apps/fire",
        "external_url": "http://itunes.apple.com/us/app/fire-2-field-recorder/id436241643?mt=8"
      },
      "permalink_url": "http://soundcloud.com/jwagener/bassy",
      "artwork_url": "http://i1.sndcdn.com/artworks-000002938592-960ejc-large.jpg?5e64f12",
      "waveform_url": "http://w1.sndcdn.com/bxaiyNJt3vWK_m.png",
      "stream_url": "http://api.soundcloud.com/tracks/6770077/stream",
      "download_url": "http://api.soundcloud.com/tracks/6770077/download",
      "playback_count": 335,
      "download_count": 78,
      "favoritings_count": 1,
      "comment_count": 1,
      "attachments_uri": "http://api.soundcloud.com/tracks/6770077/attachments"
    }
  ]
}

Properties

name description example value
id integer ID 123
created_at timestamp of creation "2009/08/13 18:30:10 +0000"
user_id user-id of the owner 343
user mini user representation of the owner {id: 343, username: "Doctor Wilson"...}
title track title "S-Bahn Sounds"
permalink permalink of the resource "sbahn-sounds"
permalink_url URL to the SoundCloud.com page "http://soundcloud.com/bryan/sbahn-sounds"
uri API resource URL "http://api.soundcloud.com/tracks/123"
sharing public/private sharing "public"
embeddable_by who can embed this track or playlist "all", "me", or "none"
purchase_url external purchase link "http://amazon.com/buy/a43aj0b03"
artwork_url URL to a JPEG image "http://i1.sndcdn.com/a....-large.jpg?142a848"

JPEG, PNG and GIF are accepted when uploading and will be encoded to multiple JPEGs in these formats:

  • t500x500: 500×500
  • crop: 400×400
  • t300x300: 300×300
  • large: 100×100 (default)
  • t67x67: 67×67 (only on artworks)
  • badge: 47×47
  • small: 32×32
  • tiny: 20×20 (on artworks)
  • tiny: 18×18 (on avatars)
  • mini: 16×16
  • original: (originally uploaded image)

The URL is pointing to the format large by default. If you want to use a different format you have to replace large with the specific format name in the image URL:

For example:

http://i1.sndcdn.com/avatars-000000011308-xq0whu-large.jpg?b17c165

to

http://i1.sndcdn.com/avatars-000000011308-xq0whu-crop.jpg?b17c165

description HTML description "my first track"
label label mini user object {id:123, username: "BeatLabel"...}
duration duration in milliseconds 1203400
genre genre "HipHop"
shared_to_count number of sharings (if private) 45
tag_list list of tags "tag1 \"hip hop\" geo:lat=32.444 geo:lon=55.33"

The tag_list property contains a list of tags seperated by spaces. Multiword tags are quoted in doublequotes. We also support machine tags that follow the pattern NAMESPACE:KEY=VALUE. For example:

  • geo:lat=43.555
  • camel:size=medium
  • “machine:tag=with space”

Machine tags are not revealed to the user on the track pages.

label_id id of the label user 54677
label_name label name "BeatLabel"
release release number 3234
release_day day of the release 21
release_month month of the release 5
release_year year of the release 2001
streamable streamable via API (boolean) true

This will aggregate the playlists tracks streamable attribute. Its value will be nil if not all tracks have the same streamable value.

downloadable downloadable (boolean) true

This will aggregate the playlists tracks downloadable attribute. Its value will be nil if not all tracks have the same downloadable value.

ean EAN identifier for the playlist "123-4354345-43"
playlist_type playlist type "recording"

Possible values:

  • “ep single”
  • “album”
  • “compilation”
  • “project files”
  • “archive”
  • “showcase”
  • “demo”
  • “sample pack”
  • “other”

Subresources

Methods Path Description
GET, POST, PUT, DELETE /playlists/{id}/shared-to/users users who have access to the track
GET, POST, PUT, DELETE /playlists/{id}/shared-to/emails email addresses who are invited to the playlist
GET, PUT /playlists/{id}/secret-token secret token of the playlist

Filters

Parameter Type Description
q string a string to search for (see search documentation)

/groups

Groups have members and contributed tracks.

Example

$ curl "http://api.soundcloud.com/groups/3.json?client_id=YOUR_CLIENT_ID"
{
  "id": 3,
  "created_at": "2009/06/18 15:46:46 +0000",
  "permalink": "made-with-ableton-live",
  "name": "Made with Ableton Live!",
  "short_description": "tracks produced with Ableton Live! music software, no DJ mixes!",
  "description": "send your tracks, no DJ mixes please!",
  "uri": "http://api.soundcloud.com/groups/3",
  "artwork_url": "http://i1.sndcdn.com/artworks-000000481400-f0ynk3-large.jpg?142a848",
  "permalink_url": "http://soundcloud.com/groups/made-with-ableton-live",
  "creator": {
    "id": 1433,
    "permalink": "matas",
    "username": "matas",
    "uri": "http://api.soundcloud.com/users/1433",
    "permalink_url": "http://soundcloud.com/matas",
    "avatar_url": "http://i1.sndcdn.com/avatars-000001548772-zay6dy-large.jpg?142a848"
  }
}

Properties

name description example value
id integer ID 123
uri API resource URL http://api.soundcloud.com/comments/32562
created_at timestamp of creation "2009/08/13 18:30:10 +0000"
permalink permalink of the resource "sbahn-sounds"
permalink_url URL to the SoundCloud.com page "http://soundcloud.com/bryan/sbahn-sounds"
artwork_url URL to a JPEG image "http://i1.sndcdn.com/a....-large.jpg?142a848"

JPEG, PNG and GIF are accepted when uploading and will be encoded to multiple JPEGs in these formats:

  • t500x500: 500×500
  • crop: 400×400
  • t300x300: 300×300
  • large: 100×100 (default)
  • t67x67: 67×67 (only on artworks)
  • badge: 47×47
  • small: 32×32
  • tiny: 20×20 (on artworks)
  • tiny: 18×18 (on avatars)
  • mini: 16×16
  • original: (originally uploaded image)

The URL is pointing to the format large by default. If you want to use a different format you have to replace large with the specific format name in the image URL:

For example:

http://i1.sndcdn.com/avatars-000000011308-xq0whu-large.jpg?b17c165

to

http://i1.sndcdn.com/avatars-000000011308-xq0whu-crop.jpg?b17c165

name name of the group "Field Recordings"
description description of the group "field recordings from across the world"
short_description short description of the group "field recordings!"
creator mini user representation of the owner {id: 343, username: "Doctor Wilson"...}

Subresources

Methods Path Description
GET /groups/{id} a group
GET /groups/{id}/moderators list of users who moderate the group
GET /groups/{id}/members list of users who joined the group
GET /groups/{id}/contributors list of users who contributed a track to the group
GET /groups/{id}/users list of users who contributed to, joined or moderate the group
GET /groups/{id}/tracks list of contributed and approved tracks
GET /groups/{id}/pending_tracks list of contributed but not approved tracks (for moderators)
GET, PUT, DELETE /groups/{id}/pending_tracks/{id} a contributed but not approved track (for moderators)
GET, POST /groups/{id}/contributions list of contributed tracks (for moderators). POST creates contribution
GET, DELETE /groups/{id}/contributions/{id} a contributed track (for moderators)

Filters

Parameter Type Description
q string a string to search for (see search documentation)

/comments

Comments can be made on tracks by any user who has access to a track, except for non commentable tracks. As you see in the SoundCloud player comments can also be associated with a specific timestamp in a track.

Example

$ curl "http://api.soundcloud.com/comments/13685794.json?client_id=YOUR_CLIENT_ID"
{
  "id": 13685794,
  "created_at": "2011/04/06 14:55:30 +0000",
  "user_id": 1505645,
  "track_id": 9740245,
  "timestamp": 55593,
  "body": "best jehst! :D",
  "uri": "http://api.soundcloud.com/comments/13685794",
  "user": {
    "id": 1505645,
    "permalink": "big-blues",
    "username": "four 2wenty",
    "uri": "http://api.soundcloud.com/users/1505645",
    "permalink_url": "http://soundcloud.com/big-blues",
    "avatar_url": "http://i1.sndcdn.com/avatars-000003153897-rx3j9l-large.jpg?142a848"
  }
}

Properties

name description example value
id integer ID 123
uri API resource URL "http://api.soundcloud.com/comments/32562"
created_at timestamp of creation "2009/08/13 18:30:10 +0000"
body HTML comment body "i love this beat!"
timestamp associated timestamp in milliseconds 55593
user_id user id of the owner 343
user mini user representation of the owner {id: 343, username: "Doctor Wilson"...}
track_id the track id of the related track 54

/me

The /me resource allows you to get information about the authenticated user and easily access his related subresources like tracks, followings, followers, groups and so on.

Example

$ curl "https://api.soundcloud.com/me.json?oauth_token=A_VALID_TOKEN"
{
  "id": 3207,
  "permalink": "jwagener",
  "username": "Johannes Wagener",
  "uri": "https://api.soundcloud.com/users/3207",
  "permalink_url": "http://soundcloud.com/jwagener",
  "avatar_url": "http://i1.sndcdn.com/avatars-000001552142-pbw8yd-large.jpg?142a848",
  "country": "Germany",
  "full_name": "Johannes Wagener",
  "city": "Berlin",
  "description": "<b>Hacker at SoundCloud</b>\r\n\r\nSome of my recent Hacks:\r\n\r\nsoundiverse.com \r\nbrowse recordings with the FiRe app by artwork\r\n\r\ntopbillin.com \r\nfind people to follow on SoundCloud\r\n\r\nchatter.fm \r\nget your account hooked up with a voicebox\r\n\r\nrecbutton.com \r\nrecord straight to your soundcloud account",
  "discogs_name": null,
  "myspace_name": null,
  "website": "http://johannes.wagener.cc",
  "website_title": "johannes.wagener.cc",
  "online": true,
  "track_count": 12,
  "playlist_count": 1,
  "followers_count": 416,
  "followings_count": 174,
  "public_favorites_count": 26,
  "plan": "Pro Plus",
  "private_tracks_count": 63,
  "private_playlists_count": 3,
  "primary_email_confirmed": true
}

Properties

name description example value
id integer ID 123
permalink permalink of the resource "sbahn-sounds"
username username "Doctor Wilson"
uri API resource URL http://api.soundcloud.com/comments/32562
permalink_url URL to the SoundCloud.com page "http://soundcloud.com/bryan/sbahn-sounds"
avatar_url URL to a JPEG image "http://i1.sndcdn.com/avatars-000011353294-n0axp1-large.jpg"
country country "Germany"
full_name first and last name "Tom Wilson"
city city "Berlin"
description description "Buskers playing in the S-Bahn station in Berlin"
discogs-name Discogs name "myrandomband"
myspace-name MySpace name "myrandomband"
website a URL to the website "http://facebook.com/myrandomband"
website-title a custom title for the website "myrandomband on Facebook"
online online status (boolean) true
track_count number of public tracks 4
playlist_count number of public playlists 5
followers_count number of followers 54
followings_count number of followed users 75
public_favorites_count number of favorited public tracks 7
avatar_data binary data of user avatar (only for uploading)
plan subscription plan of the user Pro Plus
private_tracks_count number of private tracks 34
private_playlists_count number of private playlists 6
primary_email_confirmed boolean if email is confirmed true

Subresources

All subresources that are documented in /users are also available via /me. For example /me/tracks will return the tracks owned by the user. Additionally you can access the users dashboard activities through /me/activities and his connected external accounts through /me/connections.

Methods Path Description
GET /users/{id} a user
GET /users/{id}/tracks list of tracks of the user
GET /users/{id}/playlists list of playlists (sets) of the user
GET /users/{id}/followings list of users who are followed by the user
GET, PUT, DELETE /users/{id}/followings/{id} a user who is followed by the user
GET /users/{id}/followers list of users who are following the user
GET /users/{id}/followers/{id} user who is following the user
GET /users/{id}/comments list of comments from this user
GET /users/{id}/favorites list of tracks favorited by the user
GET, PUT, DELETE /users/{id}/favorites/{id} track favorited by the user
GET /users/{id}/groups list of joined groups
GET, PUT, DELETE /users/{id}/web-profiles list of web profiles
GET /me/{id}/activities list dashboard activities
GET, POST /me/{id}/connections list of connected external profiles

/me/connections

Connections represent the external profiles (like twitter, tumblr or facebook profiles and pages) that are connected to a SoundCloud user. The connection ids can be used to share tracks and playlists to social network. This is described for tracks and playlists here.

Example

Method Resource
GET, POST /me/connections
GET /me/connections/{connection_id}

GET /me/connections

Type: Collection of connections

Retrieves connections for the authenticated user.

$ curl "https://api.soundcloud.com/me/connections.json?oauth_token=A_VALID_TOKEN"
[
  {
    "created_at": "2010/12/05 16:46:34 +0000",
    "display_name": "a facebook artist page",
    "id": 313104,
    "post_favorite": false,
    "post_publish": false,
    "service": "facebook_page",
    "type": "facebook_page",
    "uri": "https://api.soundcloud.com/connections/313104"
  },
  {
    "created_at": "2010/12/04 02:28:32 +0000",
    "display_name": "mytwittername",
    "id": 310235,
    "post_favorite": false,
    "post_publish": false,
    "service": "twitter",
    "type": "twitter",
    "uri": "https://api.soundcloud.com/connections/310235"
  },
  {
    "created_at": "2010/12/04 02:28:11 +0000",
    "display_name": "First and last name",
    "id": 310234,
    "post_favorite": false,
    "post_publish": false,
    "service": "facebook_profile",
    "type": "facebook_profile",
    "uri": "https://api.soundcloud.com/connections/310234"
  },
  {
    "created_at": "2010/03/31 14:55:59 +0000",
    "display_name": "My Myspace Name",
    "id": 105941,
    "post_favorite": false,
    "post_publish": false,
    "service": "myspace",
    "type": "myspace",
    "uri": "https://api.soundcloud.com/connections/105941"
  }
]

POST /me/connections

Result type: Unsaved Connection

Creating a new connection requires multiple steps and involves the user of your app to actively authorize on the external service.

To start do a POST to the /me/connections resource with the desired connection type and a redirect_uri. Since creating a connection requires user interaction the response will be an unsaved connection which includes an authorize_url. This authorize_url needs to be presented to the user in a webview or browser. Once the user completes the authorization a connection will be created and the user will be redirected to the given redirect_uri.

Name Type Description
service enumeration (facebook_profile, twitter, myspace), required the type of the descired connection
redirect_uri URI, required a URI
$ curl 'https://api.soundcloud.com/me/connections.json?oauth_token=A_VALID_TOKEN'  
  -F service=twitter  
  -F redirect_uri=http://yourwebapp.com/endpoint

< HTTP/1.1 202 Accepted
{
  "authorize_url": "https://soundcloud.com/connect/..."
}

The next steps are:

  • Open the authorize_url in a web view or browser.
  • The user completes the authorization on the external service.
  • If authorization positive one or more connections will be created.
  • The webview will be redirected to redirect_uri with an appended success parameter.

/me/activities

The newest activities for the logged-in user

What are activities?

Activities are the items on your Dashboard. Currently the following activity types are supported:

Type Origin
track Track
track-sharing Track and Sharing-Note
comment Comment with Mini-User and Mini-Track
favoriting Mini-Track and Mini-User

Activities are always ordered by most recent activity first.

Representation

This is the general structure of activities (example: a comment on one of the users tracks):

$ curl 'https://api.soundcloud.com/me/activities?limit=1&oauth_token=A_VALID_TOKEN'

{
  "next_href": "https://api.soundcloud.com/...?cursor=81923e19...",
  "collection": [
    {
      "type":       "comment",
      "created_at": "2011/07/21 09:55:19 +0000",
      "tags":       "own, affiliated",
      "origin": {
        ...
      }
    },
    ...
  ]
}

Origin holds the objects the activity happend on.

Tags are not the tags on tracks or playlist, but categorize the activity. The following tags exist:

Type Description
exclusive A sharing to only a handful of people
affiliated An activity from somebody the logged-in user follows
first The first sharing from a user the logged-in user does not follow
own An activity on one of the logged-in users tracks
conversation A comment which is in reaction to a comment made earlier

Pagination

You can limit the number of activities by using the ?limit= query parameter.

Activities do not support the offset query parameter. Instead they support linked partitions. Every collection of activities includes a link to the next collection of activities (if such a collection exists) with the parameter next-href.

A JSON example can be found in the representation above. Here is an XML example:

$ curl 'https://api.soundcloud.com/me/activities?limit=1&oauth_token=A_VALID_TOKEN'

<?xml version="1.0" encoding="UTF-8"?>
<activities next-href="https://api.soundcloud.com/me/activities?cursor=0fc02662-1d76-11e0-8c9a-48ea6afb1384" type="array">
  <activity>
    ...
  </activity>
  ...
</activities>

Each result from the /me/activities endpoint will include a next_href property if there are more pages of results. The next_href property will be a URI with a cursor parameter that can be used to fetch the next page of results. The future_href property can be used to poll for updated results.

Resources

Methods Path Description
GET /me/activities Recent activities
GET /me/activities/all Recent activities
GET /me/activities/tracks/affiliated Recent tracks from users the logged-in user follows
GET /me/activities/tracks/exclusive Recent exclusively shared tracks
GET /me/activities/all/own Recent activities on the logged-in users tracks

/apps

All tracks that are created and uploaded using a published app include a created_with object which describes the app:

{
  ...
  "title": "track title",
  "created_with": {
    "id": 124,
    "name": "SoundCloud iPhone",
    "uri": "http://api.soundcloud.com/apps/124",
    "permalink_url": "http://soundcloud.com/apps/iphone"
  },
  ...
}

Example

Using the /apps/{id}/tracks subresource it's possible to get a list of all public tracks that were created with a specific app:

$ curl "http://api.soundcloud.com/apps/124/tracks?client_id=YOUR_CLIENT_ID&limit=3"
[
  {
    "id": 13158665,
    "created_at": "2011/04/06 15:37:43 +0000",
    "user_id": 3699101,
    "duration": 18109,
    "commentable": true,
    "state": "finished",
    "sharing": "public",
    "tag_list": "soundcloud:source=iphone-record",
    "permalink": "munching-at-tiannas-house",
    "description": null,
    "streamable": true,
    "downloadable": true,
    "genre": null,
    "release": null,
    "purchase_url": null,
    "label_id": null,
    "label_name": null,
    "isrc": null,
    "video_url": null,
    "track_type": "recording",
    "key_signature": null,
    "bpm": null,
    "title": "Munching at Tiannas house",
    "release_year": null,
    "release_month": null,
    "release_day": null,
    "original_format": "m4a",
    "original_content_size": 102345212,
    "license": "all-rights-reserved",
    "uri": "http://api.soundcloud.com/tracks/13158665",
    "permalink_url": "http://soundcloud.com/user2835985/munching-at-tiannas-house",
    "artwork_url": null,
    "waveform_url": "http://w1.sndcdn.com/fxguEjG4ax6B_m.png",
    "user": {
      "id": 3699101,
      "permalink": "user2835985",
      "username": "user2835985",
      "uri": "http://api.soundcloud.com/users/3699101",
      "permalink_url": "http://soundcloud.com/user2835985",
      "avatar_url": "http://a1.sndcdn.com/images/default_avatar_large.png?142a848"
    },
    "stream_url": "http://api.soundcloud.com/tracks/13158665/stream",
    "download_url": "http://api.soundcloud.com/tracks/13158665/download",
    "playback_count": 0,
    "download_count": 0,
    "favoritings_count": 0,
    "comment_count": 0,
    "created_with": {
      "id": 124,
      "name": "SoundCloud iPhone",
      "uri": "http://api.soundcloud.com/apps/124",
      "permalink_url": "http://soundcloud.com/apps/iphone"
    },
    "attachments_uri": "http://api.soundcloud.com/tracks/13158665/attachments"
  },
  {
    "id": 13158638,
    "created_at": "2011/04/06 15:37:03 +0000",
    "user_id": 4047020,
    "duration": 10478,
    "commentable": true,
    "state": "finished",
    "sharing": "public",
    "tag_list": "soundcloud:source=iphone-record",
    "permalink": "sounds-from-wednesday",
    "description": null,
    "streamable": true,
    "downloadable": true,
    "genre": null,
    "release": null,
    "purchase_url": null,
    "label_id": null,
    "label_name": null,
    "isrc": null,
    "video_url": null,
    "track_type": "recording",
    "key_signature": null,
    "bpm": null,
    "title": "Sounds from Wednesday afternoon",
    "release_year": null,
    "release_month": null,
    "release_day": null,
    "original_format": "m4a",
    "original_content_size": 104532043,
    "license": "all-rights-reserved",
    "uri": "http://api.soundcloud.com/tracks/13158638",
    "permalink_url": "http://soundcloud.com/user7912435/sounds-from-wednesday",
    "artwork_url": "http://i1.sndcdn.com/artworks-000006162261-qqme8i-large.jpg?142a848",
    "waveform_url": "http://w1.sndcdn.com/8sz4wHUT2qIL_m.png",
    "user": {
      "id": 4047020,
      "permalink": "user7912435",
      "username": "user7912435",
      "uri": "http://api.soundcloud.com/users/4047020",
      "permalink_url": "http://soundcloud.com/user7912435",
      "avatar_url": "http://a1.sndcdn.com/images/default_avatar_large.png?142a848"
    },
    "stream_url": "http://api.soundcloud.com/tracks/13158638/stream",
    "download_url": "http://api.soundcloud.com/tracks/13158638/download",
    "playback_count": 0,
    "download_count": 0,
    "favoritings_count": 0,
    "comment_count": 0,
    "created_with": {
      "id": 124,
      "name": "SoundCloud iPhone",
      "uri": "http://api.soundcloud.com/apps/124",
      "permalink_url": "http://soundcloud.com/apps/iphone"
    },
    "attachments_uri": "http://api.soundcloud.com/tracks/13158638/attachments"
  },
  {
    "id": 13158597,
    "created_at": "2011/04/06 15:36:06 +0000",
    "user_id": 3375985,
    "duration": 20147,
    "commentable": true,
    "state": "finished",
    "sharing": "public",
    "tag_list": "soundcloud:source=iphone-record",
    "permalink": "stay-tuned-for-details",
    "description": null,
    "streamable": true,
    "downloadable": true,
    "genre": null,
    "release": null,
    "purchase_url": null,
    "label_id": null,
    "label_name": null,
    "isrc": null,
    "video_url": null,
    "track_type": "recording",
    "key_signature": null,
    "bpm": null,
    "title": "Stay tuned for details",
    "release_year": null,
    "release_month": null,
    "release_day": null,
    "original_format": "m4a",
    "original_content_size": 20345312,
    "license": "all-rights-reserved",
    "uri": "http://api.soundcloud.com/tracks/13158597",
    "permalink_url": "http://soundcloud.com/khamelijon/stay-tuned-for-details",
    "artwork_url": null,
    "waveform_url": "http://w1.sndcdn.com/8HptBHMeKmRg_m.png",
    "user": {
      "id": 3375985,
      "permalink": "khamelijon",
      "username": "Khamelijon",
      "uri": "http://api.soundcloud.com/users/3375985",
      "permalink_url": "http://soundcloud.com/khamelijon",
      "avatar_url": "http://i1.sndcdn.com/avatars-000002797462-enuzs1-large.jpg?142a848"
    },
    "stream_url": "http://api.soundcloud.com/tracks/13158597/stream",
    "download_url": "http://api.soundcloud.com/tracks/13158597/download",
    "playback_count": 2,
    "download_count": 0,
    "favoritings_count": 0,
    "comment_count": 0,
    "created_with": {
      "id": 124,
      "name": "SoundCloud iPhone",
      "uri": "http://api.soundcloud.com/apps/124",
      "permalink_url": "http://soundcloud.com/apps/iphone"
    },
    "attachments_uri": "http://api.soundcloud.com/tracks/13158597/attachments"
  }
]

Properties

name description example value
id integer ID 123
uri API resource URL "http://api.soundcloud.com/apps/124"
permalink_url URL to the SoundCloud.com page "http://soundcloud.com/bryan/sbahn-sounds"
external_url URL to an external site "http://itunes.com/app/soundcloud"
creator username of the app creator "weatherman"

Subresources

name description example value
id integer ID 123
uri API resource URL "http://api.soundcloud.com/apps/124"
permalink_url URL to the SoundCloud.com page "http://soundcloud.com/bryan/sbahn-sounds"
external_url URL to an external site "http://itunes.com/app/soundcloud"
creator username of the app creator "weatherman"

/resolve

The resolve resource allows you to lookup and access API resources when you only know the SoundCloud.com URL.

Example

$ curl -v 'http://api.soundcloud.com/resolve.json?url=http://soundcloud.com/matas/hobnotropic&client_id=YOUR_CLIENT_ID'

< HTTP/1.1 302 Moved Temporarily
< Location: http://api.soundcloud.com/tracks/49931.json

This request will resolve and redirect to the API resource URL for the track http://soundcloud.com/matas/hobnotropic. Just follow the redirect and you will get the representation you want. The resolver supports URLs for:

  • users
  • tracks
  • playlists (sets)
  • groups
  • apps

/oembed

oEmbed is an open standard to easily embed content from oEmbed providers into your site. The SoundCloud oEmbed endpoint will serve the widget embed code for any SoundCloud URL pointing to a user, group, set or a playlist. To find out more about the oEmbed standard, have a look at oEmbed.com.

$ curl "http://soundcloud.com/oembed" \\
           -d 'format=json' \\
           -d 'url=http://soundcloud.com/forss/flickermood'
{
  "version": 1.0,
  "type": "rich",
  "provider_name": "Soundcloud",
  "provider_url": "http://soundcloud.com",
  "height": 81,
  "width": "100%",
  "title": "Flickermood by Forss",
  "description": "test",
  "html": "test"
}

Parameters

Name Default Description
url - A Soundcloud URL for a track, set, group, user.
format json (optional) Either xml, json or js (for jsonp).
callback - (optional) A function name for the jsonp callback .
maxwidth 100% (optional) The maximum width in px.
maxheight 166 or 450 (optional) The maximum height in px. The default is 166px for tracks and 450px for sets. If using the flash widget, the default is 81px for tracks and 305px for sets.
color - (optional) The primary color of the widget as a hex triplet. (For example: ff0066).
auto_play false (optional) Whether the widget plays on load.
show_comments true (optional) Whether the player displays timed comments.
iframe true (optional) Whether the new HTML5 Iframe-based Widget or the old Adobe Flash Widget will be returned.