Building with AI

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"

You are helping integrate the SoundCloud API.

Authoritative technical sources (use these; do not invent endpoints or headers):
- OpenAPI spec JSON: https://developers.soundcloud.com/docs/api/explorer/api.json
- OpenAPI spec YAML (GitHub): https://github.com/soundcloud/api/blob/master/openapi/api.yaml
- API Guide (auth, uploads, playback, pagination, errors): https://developers.soundcloud.com/docs/api/guide
- API credentials CLI (use this before a browser flow): 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"
- Register app / credential guidance (Artist Pro, Client ID & secret): https://developers.soundcloud.com/docs/api/register-app
- LLM-oriented overview: https://developers.soundcloud.com/docs/llm-context
- API Explorer (interactive browsing only, not endpoint discovery): https://developers.soundcloud.com/docs/api/explorer/open-api

Rules:
1. Parse the OpenAPI JSON before selecting an endpoint. Use the API Explorer only to try or inspect an endpoint after finding it in the spec.
2. Base URL for API calls: https://api.soundcloud.com. Token endpoint host: https://secure.soundcloud.com
3. Authentication is OAuth 2.1; PKCE is required for the authorization code flow. Prefer the flows and parameters described in the API Guide.
4. Send access tokens on API requests using the header: Authorization: OAuth <access_token> (unless the spec documents a different requirement for a specific endpoint).
5. 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.
6. 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.
7. Respect rate limits (including play-stream limits). On HTTP 429, back off exponentially and surface errors clearly.
8. Many list endpoints support pagination with linked_partitioning=true and a next_href field; follow it until absent.
9. Not all tracks are playable for every client; handle preview/blocked/streamable states as documented.
10. Never hardcode client_id, client_secret, or tokens; load them from environment variables or a secrets manager.
11. Comply with the SoundCloud API Terms of Use and attribution/branding requirements when shipping a product.

Using the SoundCloud OpenAPI spec JSON at https://developers.soundcloud.com/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.

Using the SoundCloud OpenAPI spec JSON at https://developers.soundcloud.com/docs/api/explorer/api.json, write a Python function get_related_artists(user_urn: str, access_token: str, limit: int = 10) that:

- Calls GET https://api.soundcloud.com/users/{user_urn}/related with Authorization: OAuth <access_token>
- Passes limit and linked_partitioning=true; returns the user list and next_href if present
- Uses a SoundCloud user URN for user_urn (e.g. soundcloud:users:948745750)
- Raises a clear exception on non-success HTTP status codes, including 401 and 429

Use httpx or requests. Do not embed credentials; accept the token as an argument.

Using the SoundCloud OpenAPI spec JSON at https://developers.soundcloud.com/docs/api/explorer/api.json, write a Python function get_related_tracks(track_urn: str, access_token: str, limit: int = 10) that:

- Calls GET https://api.soundcloud.com/tracks/{track_urn}/related with Authorization: OAuth <access_token>
- Passes limit, access=playable, and linked_partitioning=true; returns the track list and next_href if present
- Uses a SoundCloud track URN for track_urn (e.g. soundcloud:tracks:308946187)
- Raises a clear exception on non-success HTTP status codes, including 401 and 429

Use httpx or requests. Do not embed credentials; accept the token as an argument.

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.

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).

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.