SoundCloud for Developers

Discover, connect and build

Building with AI

Use this page with large language models and coding assistants (Cursor, GitHub Copilot, ChatGPT, Claude, and similar tools). It points to machine-readable API reference material, a reusable system-style prompt you can paste into your assistant, and example prompts for common integration tasks.

For a compact facts-and-patterns summary optimized for agents, see LLM context.

OpenAPI specification

The SoundCloud HTTP API is described in an OpenAPI (Swagger) document consumed by the interactive explorer. Use it as the source of truth for paths, parameters, request bodies, and response shapes instead of guessing from informal examples.

Pair the spec with Get an API key (registering an app and credentials) and the human-written API Guide for authentication flows, upload and playback behavior, pagination, and error handling.

Recommended prompt for coding assistants

Copy everything inside the block below into your assistant as a project rule, system prompt, or first message when generating SoundCloud API code.

You are helping integrate the SoundCloud API.

Authoritative technical sources (use these; do not invent endpoints or headers):
- OpenAPI / Swagger UI: https://developers.soundcloud.com/docs/api/explorer/open-api
- OpenAPI spec JSON: /docs/api/explorer/api.json
- API Guide (auth, uploads, playback, pagination, errors): https://developers.soundcloud.com/docs/api/guide
- Register app / credentials (Artist Pro, Client ID & secret): https://developers.soundcloud.com/docs/api/register-app
- LLM-oriented overview: https://developers.soundcloud.com/docs/llm-context

Rules:
1. Base URL for API calls: https://api.soundcloud.com. Token endpoint host: https://secure.soundcloud.com
2. Authentication is OAuth 2.1; PKCE is required for the authorization code flow. Prefer the flows and parameters described in the API Guide.
3. Send access tokens on API requests using the header: Authorization: OAuth <access_token> (unless the spec documents a different requirement for a specific endpoint).
4. Access tokens expire after roughly one hour. Refresh tokens are single-use; implement refresh without infinite retry loops. Refreshing and reusing tokens until they are close to expiry avoids unnecessary token exchanges that can hit rate limits on new-token requests.
5. Client Credentials token exchange is rate-limited (per app and per IP). Cache access tokens; renew with the refresh_token grant instead of requesting new client_credentials tokens on every startup or request.
6. Respect rate limits (including play-stream limits). On HTTP 429, back off exponentially and surface errors clearly.
7. Many list endpoints support pagination with linked_partitioning=true and a next_href field; follow it until absent.
8. Not all tracks are playable for every client; handle preview/blocked/streamable states as documented.
9. Never hardcode client_id, client_secret, or tokens; load them from environment variables or a secrets manager.
10. Comply with the SoundCloud API Terms of Use and attribution/branding requirements when shipping a product.

Example prompts

Adapt the placeholders (YOUR_CLIENT_ID, language, framework) to your project.

Implement search with pagination

Using the SoundCloud OpenAPI spec JSON at /docs/api/explorer/api.json (and the API Guide), write a Python function search_tracks(query: str, access_token: str, limit: int = 20) that:

- Calls the track search endpoint on https://api.soundcloud.com with Authorization: OAuth <access_token>
- Uses linked_partitioning=true and returns a list of results plus the next_href URL if more pages exist
- Raises a clear exception on non-success HTTP status codes, including 401 and 429

Use httpx or requests. Do not embed my client secret; accept the token as an argument.

Authorization Code flow with PKCE (web app)

I am building a server-side web app that needs user-delegated access (uploads, /me). Using the SoundCloud API Guide section on authentication, outline the Authorization Code + PKCE flow step by step, then produce:

1. Pseudocode for generating PKCE verifier and challenge
2. The exact authorize URL query parameters
3. The token exchange POST to https://secure.soundcloud.com/oauth/token with the correct grant_type and fields
4. A note on how to store access_token, refresh_token, and expires_in securely

Assume I already registered a redirect URI in the SoundCloud app settings. Use YOUR_CLIENT_ID as a placeholder only.

Client Credentials for public resources

Write a small Node.js script that obtains a Client Credentials access token from https://secure.soundcloud.com/oauth/token using HTTP Basic auth (base64 of client_id:client_secret from environment variables), then calls the resolve endpoint for a public SoundCloud track URL.

Log only HTTP status and high-level errors, not tokens. Handle 429 with a short backoff retry (max 3 attempts).

Widget and embeds

I want to embed a SoundCloud player on a static site. Compare the oEmbed endpoint (https://developers.soundcloud.com/docs/oembed) with the HTML5 Widget API (https://developers.soundcloud.com/docs/api/html5-widget) and recommend which to use for a simple iframe embed vs custom playback controls. Include one minimal HTML example for the iframe case.

Tools

These patterns work with any assistant that can follow URLs and keep instructions in context. Point the model at this page, the LLM context summary, and the API Explorer for the best results.