Song Request Invalid Request Feel Free to Try Again With a Valid Token

API Guide

With SoundCloud API yous can build applications that have music to the next level. With this guide nosotros explain and provide lawmaking examples for a lot of common integration use cases like playing and uploading tracks, liking a playlist or discovering new music. If you're looking for more in depth information, feel gratis to spring to our API Explorer.

Now become ahead and jump to the department you're most interested in and go started.

Authentication

• Sign in with SoundCloud
• Authority Code Menses
• Client Credentials Token Exchange Flow
• Refreshing Tokens
• Mobile and Desktop Applications
• Accessing Resources
• Getting Information near Authenticated User

Uploading Tracks

• Uploading Audio Files
• Updating Metadata
• Creating Playlists
• Adding Tracks to a Playlist
• Accessing Playlists

Playing Tracks

• Embedding the SoundCloud Widget
• Streaming Tracks

Follow & Like

Search

Pagination

SoundCloud URLs

Cross Domain Requests

Errors

• HTTP Status Codes

Authentication

In social club to integrate with Soundcloud you need to authorize your application. SoundCloud authentication uses OAuth two.0, a popular open standard used by many API providers. OAuth 2.0 allows users to authorize the awarding without disclosing their username and password.

There are different ways to authenticate with OAuth, depending on the needs of an application you lot're building.

Supported Authorization flows:

• Authorization Code: Your awarding intends to perform actions on a user'due south behalf (rail upload) equally well as access user's data (their account, including whatsoever private tracks or playlists that they take created or that take been shared with them). In that case your app has to get permission from Soundcloud, and the user, to access SoundCloud on their behalf.
• Client Credentials: Your application intends to access public resources merely. That implies searching for a rail, or a playlist, playback and URL resolution. For these purposes you lot do not crave a user session, only an authorized app.

In farther sections you can observe more detailed information well-nigh each of the authentication methods.

Flow	User Resources Access	Server-side Implementation
Potency Code	Yes	Yes
Customer Credentials	No	Yes

Sign in with SoundCloud

Yous can simplify your registration and sign in procedure past using a Connect with SoundCloud button. This lets your user know that they can annals for your app with one click using their SoundCloud business relationship. It also grants your app access to their business relationship and gives y'all the ability to upload tracks, create playlists and otherwise act on their behalf.

Authorization Code Flow

To authenticate your server-side web application you tin can call our API directly using the API credentials you obtained when you registered your app and redirect the user to the authorization URL and then that they can log in and approve your request.

• Curl

              # authenticate your app through SC Connect # open in the browser  "https://api.soundcloud.com/connect?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code"            

Security Advice

Use the state parameter for CSRF protection. Laissez passer a sufficient random nonce hither and verify this nonce over again after retrieving the token.

A pop-up window will exist opened allowing the user to log in to SoundCloud and approve your app's authorization request. If the user is already signed into SoundCloud, they volition be able to authorize your request in ane click.

Users of your app will be redirected to the SoundCloud Connect screen.

If the user approves your dominance request, they will be sent to the redirect_uri you specified when registering your app. Excerpt the code parameter from the query string and use it to obtain an access token.

• Curl

              # obtain the access token  $ curl -X POST "https://api.soundcloud.com/oauth2/token" \      -H  "accept: awarding/json; charset=utf-viii" \      -H  "Content-Type: application/x-world wide web-form-urlencoded" \      --data-urlencode "grant_type=authorization_code" \      --data-urlencode "client_id=YOUR_CLIENT_ID" \      --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \      --information-urlencode "redirect_uri=YOUR_REDIRECT_URI" \      --data-urlencode "code=YOUR_CODE"            

The returned object has an access_token property and a refresh_token belongings too every bit expires_in and scope. Yous should now store the object in a database or a data storage of your choice. Associate it with the user information technology belongs to and utilise the access_token from at present on instead of sending the user through the dominance menses on each API interaction. Use the refresh_token to automatically renew the expired token.

• Scroll

              # make an authenticated call  $ whorl "https://api.soundcloud.com/me" \        -H "accept: application/json; charset=utf-8" \        -H "Authorization: OAuth ACCESS_TOKEN"            

Client Credentials Token Exchange Menses

With applications, such as CLIs, or pure back-cease services yous would cosign the awarding itself rather than a user. For instance, you might want to build an artist's website where you merely need an admission to their tracks, playlists, or user information. There is no need to get through the connect flow, equally SoundCloud API provides the Customer Credentials Catamenia for these purposes. Y'all pass along the client_id and client_secret you have acquired at registration to authenticate and get a token.

• Curl

              # obtain the access token  $ curl -X POST "https://api.soundcloud.com/oauth2/token" \      -H  "accept: application/json; charset=utf-8" \      -H  "Content-Type: application/x-www-form-urlencoded" \      --data-urlencode "grant_type=client_credentials" \      --data-urlencode "client_id=YOUR_CLIENT_ID" \      --data-urlencode "client_secret=YOUR_CLIENT_SECRET"            

Same way every bit with the Say-so Lawmaking flow you receive an object that has an access_token, refresh_token properties as well as expires_in and telescopic. Store the object in a database or a data storage of your choice. Associate information technology with the user it belongs to and use the access_token for requesting information from our API. Apply the refresh_token to automatically renew the expired token.

Please exist aware there is a rate limiting on amount of token you lot tin can request through the Client Credentials Flow: 50 tokens in 12h per app, and 30 tokens in 1h per IP address. In order to not hit the limit we highly recommend reusing ane token between instances of your service and implementing the Refresh Token flow to renew tokens.

Refreshing Tokens

As the access tokens expire you will demand to periodically refresh them. Currently a token lives around 1 hour. You tin can ready an automatic process that checks the expiration time of a electric current token and updates information technology using the provided refresh_token. Delight note that each refresh token can just exist used one time.

• Coil

              # refresh token  $ gyre -10 Mail "https://api.soundcloud.com/oauth2/token" \      -H  "accept: awarding/json; charset=utf-eight" \      -H  "Content-Type: application/ten-www-course-urlencoded" \      --data-urlencode "grant_type=refresh_token" \      --data-urlencode "client_id=YOUR_CLIENT_ID" \      --data-urlencode "client_secret=YOUR_CLIENT_SECRET" \      --information-urlencode "refresh_token=YOUR_TOKEN" \            

Mobile and Desktop Applications

Y'all authenticate mobile and desktop applications the aforementioned way you do for web applications. To make the flow smoother, yous can use a redirect_uri with a custom protocol scheme and set your app as a handler for that protocol scheme. For example, your redirect_uri could exist something like my-app://soundcloud/callback.

When building apps for mobile devices, we recommend using our mobile optimized connect screen by setting display=popup in the authority URL query string.

Mobile optimized connect screen.

Accessing Resource

All Soundcloud resources (tracks, playlists, users) can just exist accessed by an authenticated applications. That said, every request to our API requires an Authorization header in the following format:

-H "Say-so: OAuth ACCESS_TOKEN"

Note that requests without the header will be rejected with a 401 Unauthorized error. Bank check the Authentication department to learn about supported auth methods.

Getting Information about the Authenticated User

Once the user has signed into SoundCloud and canonical your app'south say-so request, yous will be able to access their profile and act on their behalf. We have provided a convenient endpoint for accessing information about the authenticated user.

• Curl

              $ curl "https://api.soundcloud.com/me" \        -H "accept: application/json; charset=utf-eight" \        -H "Authorisation: OAuth ACCESS_TOKEN"            

Uploading Tracks

Tracks are core to SoundCloud. Our API gives you the ability to upload, manage and share tracks. Your app tin take an sound file and upload it to a user'southward SoundCloud account. You lot can also manage metadata (including tags) or add the rails to playlists. We support the following formats: AIFF, Wave, FLAC, OGG, MP2, MP3, AAC, AMR and WMA.

Uploading Audio Files

To upload a track, send a Postal service request with a multipart/form-information media type to the /tracks endpoint.

Request bodies for runway uploads via the API may not exist larger than %stiff 500MB.

• Curl

              $ curl -Ten POST "https://api.soundcloud.com/tracks" \        -H  "have: awarding/json; charset=utf-eight" \        -H "Dominance: OAuth ACCESS_TOKEN" \        -H  "Content-Type: multipart/course-information" \        -F "track[title]=YOUR_TITLE" \        -F "track[asset_data]=@PATH_TO_A_FILE"            

If successful, your track will immediately exist queued up for encoding.

Updating Metadata

In social club to update a rails's metadata, send a PUT asking to the /tracks/:id endpoint, passing in the path of the rails resource and the properties y'all desire to update.

You can update the track artwork using the artwork_data parameter. Please note that at this fourth dimension information technology is not possible to update the actual track sound file.

For a full list of properties that can be attack a runway resource, see the endpoint reference.

• Coil

              # Multipart asking $ curlicue -X PUT "https://api.soundcloud.com/tracks/TRACK_ID" \        -H  "accept: application/json; charset=utf-8" \        -H  "Content-Type: mmultipart/form-information" \        -H "Say-so: OAuth ACCESS_TOKEN" \        -F "track[championship]=YOUR_TITLE" \        -F "track[description]=YOUR_DESCRIPTION"  \        -F "track[artwork_data]=PATH_TO_FILE"  # Json request $ curl -X PUT "https://api.soundcloud.com/tracks/TRACK_ID"  \       -H  "have: application/json; charset=utf-viii" \        -H  "Content-Type: awarding/json"  \        -H  "Authorization: OAuth ACCESS_TOKEN"  \        -d '{"track":{"title":"NEW TITLE"}}'            

Creating Playlists

Playlists allow you to organize tracks into groups that can be shared together. For example, tracks in an album or in a specific collection can be grouped together using a playlist and then shared to the world. Y'all can add any tracks to a playlist and a runway can belong to multiple playlists. Playlists can exist either individual or public.

You create playlists through our API by sending the POST request to the /playlists endpoint and providing the information most the playlist, including a list of track ids.

• Curl

              $ curlicue -X POST "https://api.soundcloud.com/playlists" \        -H  "accept: application/json; charset=utf-8" \        -H  "Content-Type: application/json" \        -H "Say-so: OAuth ACCESS_TOKEN" \        -d "{'playlist': {'title':'YOUR_TITLE', 'clarification':YOUR_DESCRIPTION, 'sharing':'public', 'tracks':[{'id':ane},{'id':two},{'id':three}]}}"            

Calculation Tracks to a Playlist

Once a playlist has been created, you can keep to add together tracks to it by updating the tracks belongings. You tin also update the playlist's metadata.

• Whorl

              $ scroll -10 PUT "https://api.soundcloud.com/playlists/PLAYLIST_ID" \        -H  "accept: application/json; charset=utf-8" \        -H  "Content-Type: application/json" \        -H "Authority: OAuth ACCESS_TOKEN" \        -d "{'playlist': {'tracks':[{'id':i}, {'id':2}, {'id':3}]}}"            

Accessing Playlists

To get a list of tracks in a playlists, send a Become request to the /playlists/:id endpoint with the playlist id.

• Curl

              $ curl -X GET "https://api.soundcloud.com/playlists/PLAYLIST_ID?show_tracks=false" \        -H  "accept: application/json; charset=utf-viii" \        -H "Authorization: OAuth ACCESS_TOKEN"            

Encounter likewise:

• /playlists endpoint reference documentation.

Playing Tracks

Yeah, you tin also play tracks and playlists from your application. Depending on your needs, you tin can embed a player widget, or feed a stream url into your ain sound player. You tin also use our Widget API to command the role player and handle events.

Embedding a SoundCloud Widget

If you have the URL of a rails or a playlist, you can go the embed code and paste it into your website. You can also practice this in your application using the oEmbed endpoint. Given a track or playlist URL, yous can retrieve all of the information yous need to embed a thespian.

Instance SoundCloud Widget

Streaming Tracks

Note if you are going to stream from our API you demand to attribute properly. Brand sure you've read our Terms and Attribution Guidelines to make sure y'all care for our creators content correctly. When using a custom thespian y'all must:

1. Credit the uploader as the creator of the track
2. Credit SoundCloud as the source by including i of the logos establish here
3. Link to the SoundCloud URL containing the work
4. If the track is private link to the profile of the creator

If you don't want to apply the SoundCloud widget, our API gives you the power to access a rails'southward stream URL and use your own actor to play tracks from SoundCloud. In club to get a URL for streaming, you can request the appropriate resource and make note of the stream_url property. Send a GET request to that URL and you will go a set of links with bachelor transcodings which yous can cull from.

Annotation that equally long every bit the track is public, y'all can access it with no user associated. If y'all would like to access the stream URL for a private track, you'll need to have an authorized user session and a secret_token provided.

• Ringlet

              # asking a rails y'all want to stream $ gyre -Ten Become "https://api.soundcloud.com/tracks/TRACK_ID" \        -H  "accept: application/json; charset=utf-8" \        -H "Authorization: OAuth ACCESS_TOKEN"  # excerpt stream_url when available from a response $ curl -X GET "https://api.soundcloud.com/tracks/TRACK_ID/stream" \          -H  "accept: application/json; charset=utf-8" \          -H "Authorization: OAuth ACCESS_TOKEN"            

Restricted Access

Not every runway is allowed for streaming off platform. A user might restrict a playback, or a track might exist behind a paywall, geo-blocked so on. In that case a runway in response wont take a stream_url available and a field access will have blocked. If you try to call /tracks/:id/streams endpoint you lot will become an error.

Soundcloud API provides iii levels of track's access:

• playable - a track is fully streamable.
• preview - a runway's preview is available.
• blocked - a track is not streamable, only metadata is provided.

Y'all can also specify the access when searching or fetching tracks to, for case, avoid showing non-streamable tracks. Our endpoints provide a filter access that accepts an inclusive list of values.

For detailed information check the API Explorer.

SoundCloud has many social features that make it easier to collaborate, share and get feedback. The primary way that SoundCloud users interact is by leaving comments on each other's tracks.

Our API allows you to leave comments on tracks by calling the POST method with the /tracks/:track_id/comments path and information near the comment. Include the timestamp to brand it a timed comment.

Note that yous cannot go out comments on tracks if the creator has disabled comments.

• Curl

              $ curl -Ten Mail service "https://api.soundcloud.com/tracks/YOUR_TRACK_ID/comments"  \        -H  "accept: application/json; charset=utf-viii" \        -H  "Content-Type: application/json; charset=utf-8" \        -H "Authorization: OAuth ACCESS_TOKEN" \        -d "{'comment':{'body':'YOUR_COMMENT'}}"            

Note that the timestamp value is in milliseconds and represents the amount of time from the beginning of the rails. If you omit the timestamp, the comment will be a non-timed one.

You can also get a list of comments for a specified track.

• Roll

              $ curl -X Get "https://api.soundcloud.com/tracks/YOUR_TRACK_ID/comments?limit=3&linked_partitioning=true" \        -H  "have: application/json; charset=utf-8" \        -H "Authority: OAuth ACCESS_TOKEN"            

See also:

• /tracks endpoint reference documentation.

Follow & Like

Your awarding can have advantage of SoundCloud's social features by allowing users to follow other users and like tracks or playlists. Following and liking allows SoundCloud users to customize their experience. Tracks created and reposted by people your user follows will exist available in their activeness feed.

Yous can follow a user using the /me/followings/:user_id endpoint.

• Curl

              $ curlicue -X PUT "https://api.soundcloud.com/me/followings/USER_ID" \        -H  "have: application/json; charset=utf-8" \        -H "Dominance: OAuth ACCESS_TOKEN"            

Liking a track or playlist is washed using the /likes/ endpoints.

• Coil

              # liking a track $ curl -Ten Mail service "https://api.soundcloud.com/likes/tracks/TRACK_ID" \        -H "accept: application/json; charset=utf-8" \        -H "Potency: OAuth ACCESS_TOKEN"  # liking a playlist $ curl -Ten Postal service "https://api.soundcloud.com/likes/playlists/PLAYLIST_ID" \        -H "take: application/json; charset=utf-8" \        -H "Authorization: OAuth ACCESS_TOKEN"            

Search

Resources such as tracks, users, playlists can be searched using our API. Almost endpoints will accept a q param which you tin can use to specify a keyword to search for in fields like title, username, description, etc. depending on the resource blazon.

• Curl

              # search pnly for playable tracks $ curl -Ten GET "https://api.soundcloud.com/tracks?q=hello&ids=1,2,3&genres=Pop,House&access=playable&limit=3&linked_partitioning=true" \        -H  "accept: application/json; charset=utf-8" \        -H "Authorization: OAuth ACCESS_TOKEN"            

You lot can also specify ranges for bpm, duration, and more.

• Gyre

              # search pnly for playable tracks $ curl -X GET "https://api.soundcloud.com/tracks?q=hello&ids=1,two,iii&genres=Popular,House&bpm%5Bfrom%5D=120&duration%5Bfrom%5D=30000&access=playable&limit=3&linked_partitioning=true" \        -H  "have: application/json; charset=utf-8" \        -H "Authorization: OAuth ACCESS_TOKEN"            

For a complete list of search fields and filters, delight bank check the /search department for the resource type you'd like to search.

Pagination

Nigh results from our API are returned equally a drove. The number of items in the collection returned is express to 50 by default with a maximum value of 200. About endpoints back up a linked_partitioning parameter that allows you to page through collections. When this parameter is passed, the response will comprise a next_href belongings if there are additional results. To fetch the side by side page of results, but follow that URI. If the response does not contain a next_href belongings, you have reached the end of the results.

• Curl

              # fetch first 25 user'due south playlists $ curl -X GET "https://api.soundcloud.com/me/playlists?show_tracks=fake&linked_partitioning=true&limit=25" \        -H  "accept: awarding/json; charset=utf-8" \        -H "Authorization: OAuth ACCESS_TOKEN"  # response contains 'next_href': "https://api.soundcloud.com/playlists?show_tracks=false&page_size=25&cursor=1234567"            

SoundCloud URLs

If you accept a permalink URL to a particular resource, only demand more information such as an ID or other holding, you can use the /resolve endpoint to extract a full representation of the resource.

• Curl

              $ ringlet -Ten Get "https://api.soundcloud.com/resolve?url=https://soundcloud.com/PERMALINK" \        -H  "accept: */*" \        -H "Authorization: OAuth ACCESS_TOKEN"            

See also:

• /resolve endpoint reference documentation.

Cross Domain Requests

Our API supports CORS for making cantankerous domain requests. This ways yous can access SoundCloud API endpoints from JavaScript running in the browser. Past requesting results formatted as JSON, you will be able to parse and apply the response immediately.

              <script src="http://code.jquery.com/jquery-ane.7.2.js"></script> <script> var url = 'https://api.soundcloud.com/tracks'; $.getJSON(url, function(tracks) {   $(tracks).each(office(track) {     panel.log(track.title);   } }); </script>            

Nosotros as well support JSONP, which can exist used by passing a callback parameter in the query cord of the URL you are requesting.

Errors

When an error occurs, our API will return an appropriate HTTP status lawmaking and an error message description.

In this section:

• HTTP Status Codes

• Curl

              # try fetching a non-existing user $ curl -Ten Go "https://api.soundcloud.com/users/INVALID_ID" \        -H  "accept: application/json; charset=utf-eight" \        -H  "Authorization: OAuth ACCESS_TOKEN"  # response 404 Fault: Not Found {   "code": 404,   "message": "404 - Not Found",   "link": "https://developers.soundcloud.com/docs/api/explorer/open-api",   "condition": "404 - Not Plant",   "errors": [     {       "error_message": "404 - Not Found"     }   ],   "error": null }            

HTTP Status Codes

The response from SoundCloud volition take an HTTP condition code that will assist you make up one's mind the cause of the error. Our API tries to utilize the appropriate HTTP status code to indicate the type of problem encountered.

Below is an overview of what those codes mean, along with some suggestions that might help you fix things.

400 Bad Request

This is likely to be caused past a programming error on your part. Check the requirements of the endpoint you're calling in the API Explorer.

401 Unauthorized

This means that nosotros were not able to authenticate you based on the information provided in the request. Make certain you're sending an Authorization header.

Our public endpoints volition work with an access token acquired through the Customer Credentials flow. Acting on behalf of another user is different. The Authentication section gives a detailed explanation of how this works.

If you're connecting using OAuth, don't forget that tokens can elapse. These will demand to be refreshed. Not doing so tin also effect in getting a 401 error.

If you need to check your application's details, use the Your Applications page. This will include the client_id for your application.

403 Forbidden

You lot don't have access to whatever it is you're asking for.

404 Non Found

Y'all're asking for something that doesn't exist. Bank check the URL that you're requesting.

406 Non Accessible

This ways it wasn't possible to respond with the format you requested. Check the Accept header that y'all're sending.

422 Unprocessable Entity

The request was valid, but one or more than of the parameters looks a lilliputian screwy. It's possible that yous sent data in the wrong format. One example would be providing an array when we expected a string.

429 Too Many Requests

To keep the amount of spam on SoundCloud as low equally possible, our API limits the rate at which you can perform certain actions. Read the Rate Limits folio to observe out more.

500 Internal Server Error

Uh-oh. Something went incorrect on our side. Nosotros're lamentable. We keep track of these, and nosotros'll effort to fix it!

503 Service Unavailable

This means that we're having some problem, and our servers are also busy to handle your request. You'll want to check for these and give your user a take chances to retry the request. We keep runway of these and try to make certain they don't happen.

504 Gateway Timeout

This means the request is taking also long. Still, information technology doesn't ever mean that we didn't receive your request. We could still be chugging away on the changes you fabricated, and this means that you may want to check before retrying.

gonzalezhimusince.blogspot.com

Source: https://developers.soundcloud.com/docs/api/guide

Share this post