openapi: 3.1.0
info:
  title: SoundCloud API
  version: "1.0.0"
  summary: SoundCloud REST API for tracks, users, playlists, search, social actions, and streaming.
  description: |
    The SoundCloud HTTP API exposes endpoints for tracks (upload, metadata,
    streaming, comments), users (/me, profile actions), playlists (CRUD),
    search/discovery, and social actions (follow, like). Authentication uses
    OAuth 2.1 with PKCE. Access tokens expire approximately every hour.

    The token endpoint is on secure.soundcloud.com; all resource endpoints are
    on api.soundcloud.com.
  contact:
    name: SoundCloud Developers
    url: https://developers.soundcloud.com/docs/api/guide
servers:
  - url: https://api.soundcloud.com
    description: SoundCloud REST API
security:
  - oauth2: [non-expiring]
tags:
  - name: Tracks
    description: Track CRUD, streaming, and comments
  - name: Users
    description: Authenticated user and profile actions
  - name: Playlists
    description: Playlist CRUD
  - name: Search
    description: Search and resolution
  - name: Social
    description: Follow and like actions
paths:
  /oauth/token:
    servers:
      - url: https://secure.soundcloud.com
    post:
      tags: [Users]
      summary: Obtain or refresh an OAuth 2.1 access token (PKCE)
      operationId: createOAuthToken
      security: []
      responses:
        "200":
          description: Access token response
  /tracks:
    get:
      tags: [Tracks, Search]
      summary: Search tracks
      operationId: searchTracks
      parameters:
        - name: q
          in: query
          schema:
            type: string
          description: Free-text query against title and description
        - name: genres
          in: query
          schema:
            type: string
        - name: access
          in: query
          schema:
            type: string
        - name: bpm
          in: query
          schema:
            type: string
        - name: duration
          in: query
          schema:
            type: string
        - name: ids
          in: query
          schema:
            type: string
        - name: linked_partitioning
          in: query
          schema:
            type: boolean
          description: Enable cursor pagination via next_href
      responses:
        "200":
          description: Track collection
    post:
      tags: [Tracks]
      summary: Upload audio file with metadata
      operationId: createTrack
      responses:
        "201":
          description: Track created
  /tracks/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      tags: [Tracks]
      summary: Retrieve track
      operationId: getTrack
      responses:
        "200":
          description: Track details
    put:
      tags: [Tracks]
      summary: Update track metadata and artwork
      operationId: updateTrack
      responses:
        "200":
          description: Track updated
  /tracks/{id}/stream:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      tags: [Tracks]
      summary: Access transcoded streaming formats for a track
      operationId: getTrackStream
      responses:
        "302":
          description: Redirect to stream URL
  /tracks/{id}/comments:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      tags: [Tracks]
      summary: List comments on a track
      operationId: listTrackComments
      responses:
        "200":
          description: Comment collection
    post:
      tags: [Tracks]
      summary: Add a timed or non-timed comment to a track
      operationId: createTrackComment
      responses:
        "201":
          description: Comment created
  /playlists:
    post:
      tags: [Playlists]
      summary: Create a playlist
      operationId: createPlaylist
      responses:
        "201":
          description: Playlist created
  /playlists/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      tags: [Playlists]
      summary: Get playlist (with optional tracks)
      operationId: getPlaylist
      parameters:
        - name: show_tracks
          in: query
          schema:
            type: boolean
          description: Set to false to exclude tracks from the response
      responses:
        "200":
          description: Playlist details
    put:
      tags: [Playlists]
      summary: Update playlist metadata or tracks
      operationId: updatePlaylist
      responses:
        "200":
          description: Playlist updated
  /resolve:
    get:
      tags: [Search]
      summary: Resolve a SoundCloud URL to an API resource representation
      operationId: resolveUrl
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
            format: uri
      responses:
        "302":
          description: Redirect to canonical API resource
        "200":
          description: Resource representation
  /me:
    get:
      tags: [Users]
      summary: Get the authenticated user's profile
      operationId: getMe
      responses:
        "200":
          description: User profile
  /me/followings/{userId}:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
    put:
      tags: [Social]
      summary: Follow a user
      operationId: followUser
      responses:
        "200":
          description: Following created
    delete:
      tags: [Social]
      summary: Unfollow a user
      operationId: unfollowUser
      responses:
        "200":
          description: Following removed
  /likes/tracks/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    post:
      tags: [Social]
      summary: Like a track
      operationId: likeTrack
      responses:
        "201":
          description: Like created
    delete:
      tags: [Social]
      summary: Unlike a track
      operationId: unlikeTrack
      responses:
        "200":
          description: Like removed
  /likes/playlists/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    post:
      tags: [Social]
      summary: Like a playlist
      operationId: likePlaylist
      responses:
        "201":
          description: Like created
    delete:
      tags: [Social]
      summary: Unlike a playlist
      operationId: unlikePlaylist
      responses:
        "200":
          description: Like removed
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: |
        OAuth 2.1 with PKCE. Access tokens are short-lived (~1 hour). Use
        Authorization: OAuth {ACCESS_TOKEN} on each request.
      flows:
        authorizationCode:
          authorizationUrl: https://secure.soundcloud.com/authorize
          tokenUrl: https://secure.soundcloud.com/oauth/token
          scopes:
            non-expiring: Non-expiring refresh-token grant
        clientCredentials:
          tokenUrl: https://secure.soundcloud.com/oauth/token
          scopes: {}
  parameters:
    Id:
      name: id
      in: path
      required: true
      schema:
        type: string