SoundCloud API — LLM Context

This page provides a structured overview of the SoundCloud developer documentation for use by LLM agents and AI-assisted development tools.

For copy-paste prompt templates and example instructions to use with coding assistants, see Building with AI.

Agent startup sequence#

Use this order when building against the SoundCloud API:

1. Parse the OpenAPI JSON to choose endpoints, fields, and request shapes.
2. If the project needs credentials, run the API CLI with remote pairing. It works in local, cloud, and coding-agent environments, then prints the Client ID and Client Secret:

   curl -fsSL https://raw.githubusercontent.com/soundcloud/api/master/scripts/sc-api-auth.mjs | node --input-type=module - --remote --name "My API App" --description "What my integration does" --website "https://example.com"

If a browser workflow is preferred, use Your Apps to create an application manually and copy the Client ID and Client Secret. The CLI remains the recommended path.

1. Use the API Guide for OAuth behavior, uploads, playback, pagination, and errors.
2. Use the API Explorer only to interactively inspect or try an endpoint after finding it in the OpenAPI document.

API Quick Reference#

• Base URL: https://api.soundcloud.com
• Auth URL: https://secure.soundcloud.com
• Authentication: OAuth 2.1 with PKCE required
• Required header: Authorization: OAuth ACCESS_TOKEN
• Token expiry: ~1 hour (use single-use refresh tokens to renew)
• Response format: JSON
• Pagination: pass linked_partitioning=true, follow next_href until absent
• Rate limits: 15,000 play-stream requests per 24h per client_id; no global aggregate limit currently enforced
• Client Credentials token limits: 50 per 12h per app, 30 per 1h per IP — cache the access token, then renew with the refresh_token grant (not a new client_credentials exchange) so you stay under these limits; refresh tokens are single-use (refresh flow)
• Upload source formats (examples): AIFF, WAVE, FLAC, OGG, MP2, MP3, AAC, AMR, WMA — full list, prep, and tips: Upload Requirements (applies to API and in-app uploads)
• Upload limits: up to 4 GB per file, 24 hours max duration per track (same article)
• Playback: SoundCloud transcodes uploads for streaming (e.g. AAC); lossless or high-quality masters sound best (see API Guide — Uploading Tracks)
• OpenAPI spec (JSON, for tools & LLMs): api.json
• OpenAPI spec (YAML on GitHub): openapi/api.yaml — updated on each API release
• Interactive API explorer: Open API Explorer — use after selecting an endpoint from the spec

Authentication Flows#

Full details: API Guide — Authentication

Documentation Map#

Guides#

API Reference#

Policy & Legal#

Common API Patterns#

Get an access token (Client Credentials)#

curl -X POST "https://secure.soundcloud.com/oauth/token" \
     -H "accept: application/json; charset=utf-8" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic <base64_encoded_credentials>" \
     --data-urlencode "grant_type=client_credentials"

Resolve a SoundCloud URL to an API resource#

curl -X GET "https://api.soundcloud.com/resolve?url=https://soundcloud.com/USERNAME/TRACK" \
     -H "Authorization: OAuth ACCESS_TOKEN"

Search tracks#

curl -X GET "https://api.soundcloud.com/tracks?q=QUERY&access=playable&limit=10&linked_partitioning=true" \
     -H "Authorization: OAuth ACCESS_TOKEN"

Stream a track#

curl -X GET "https://api.soundcloud.com/tracks/TRACK_ID/stream" \
     -H "Authorization: OAuth ACCESS_TOKEN"

Upload a track (requires Authorization Code token)#

curl -X POST "https://api.soundcloud.com/tracks" \
     -H "Authorization: OAuth ACCESS_TOKEN" \
     -H "Content-Type: multipart/form-data" \
     -F "track[title]=TITLE" \
     -F "track[artist]=ARTIST" \
     -F "track[asset_data]=@PATH_TO_FILE"

Artist metadata: set track[artist] on multipart upload; read metadata_artist from the track response; update via JSON PUT with metadata_artist inside the track object. Do not use track[metadata_artist] on upload. See API Guide — Artist metadata.

Key Constraints#

• Most API requests (except for token exchange) require an Authorization: OAuth ACCESS_TOKEN header. Requests without it return 401 Unauthorized.
• Access tokens expire after ~1 hour. Refresh tokens are single-use.
• Not all tracks are streamable. Check the access field: playable, preview, or blocked.
• Play-stream requests are rate-limited to 15,000 per 24h per client_id. Exceeding returns 429.
• Track uploads follow SoundCloud Upload Requirements (formats, 4 GB / 24 h limits, quality guidance); audio is transcoded for streaming (e.g. AAC).
• User-scoped actions (upload, follow, like, comment) require an Authorization Code token. Public-only access can use Client Credentials.
• The API supports CORS for browser-based requests.
• Pagination: default 50 items, max 200 per page. Use linked_partitioning=true and follow next_href.