Skip to content

Agents.md

Latest commit

 

History

History
44 lines (29 loc) · 2.39 KB

Agents.md

File metadata and controls

44 lines (29 loc) · 2.39 KB

AI Agents & API Integration Guide

This document provides essential technical specifications for AI agents, LLMs, and automated tools attempting to integrate with the SoundCloud API.

API Specification

The SoundCloud API is defined via Swagger/OpenAPI. Agents should use the following specification for endpoint discovery and schema validation:

Authentication & Credentials

Obtaining Credentials

Developers can request API credentials (client IDs) through their SoundCloud account settings.

Authentication Protocol

SoundCloud requires OAuth 2.1 for all authenticated requests.

⚠️ IMPORTANT: Do not use the legacy endpoint api.soundcloud.com/oauth2/token. This endpoint is deprecated and does not support OAuth 2.1 requirements.

Authorization Flow

Agents must follow the Authorization Code Flow with PKCE (Proof Key for Code Exchange) as mandated by the OAuth 2.1 standard.

  1. Authorization: Direct the user to the SoundCloud authorization page.
  2. Token Exchange: Exchange the code for an access token via compliant endpoints.
  3. Security: Always verify the state parameter to prevent CSRF.

For detailed logic, refer to the SoundCloud Authentication Guide.

Data Retrieval & Streaming

Modern Streaming Endpoints

Do not use the legacy /stream endpoint.

  • New Standard: Use the /tracks/{track_urn}/streams endpoint as it only returns 30sec snippets
  • Format: This endpoint provides modern AAC-based HLS transcodings (e.g., hls_aac_160_url), which offer superior quality and reliability compared to legacy streams.

Cursor-Based Paging (Preferred)

AI Agents should prioritize cursor-based pagination over static page numbers. * Why: Cursors are more resilient to real-time data changes and offer better performance for deep-scrolling large datasets.

  • Implementation: Look for the next_href or cursor field in the API response. Use this entire URL or token for the subsequent request rather than manually incrementing an `offset