Audius playlists API

openapi: 3.2.0
info:
  title: Audius challenges Playlists API
  description: '## Overview


    The Audius API provides REST access to the world''s largest open music catalog, built on the [Open Audio Protocol](https://openaudio.org). Use it to query and stream tracks, users, playlists, and more—perfect for building music players, discovery apps, and audio-native products.


    ## Key Capabilities


    - **Users** — Profiles, followers, following, search

    - **Tracks** — Search, trending, stream, favorites, reposts

    - **Playlists** — Create, update, browse, curate

    - **Resolve** — Look up content by Audius canonical URLs (e.g. `audius.co/artist/...`)

    - **Explore** — Trending content, charts, discovery

    - **Comments, Tips, Rewards** — Social features and engagement


    ## Authentication


    - **Read-only** — Most endpoints work without credentials. Use an API key for higher rate limits.

    - **Writes** — Upload, favorite, repost, and other mutations require an API key and secret. Get keys at [api.audius.co/plans](https://api.audius.co/plans) or [audius.co/settings](https://audius.co/settings).


    ## Resources


    - [API Docs](https://docs.audius.co/api) — Full reference and guides

    - [API Plans](https://api.audius.co/plans) — Get API keys (free tier available)

    - [Log in with Audius](https://docs.audius.co/developers/guides/log-in-with-audius) — OAuth for user actions

    - [JavaScript SDK](https://www.npmjs.com/package/@audius/sdk) — `@audius/sdk` for Node and browser

    '
  version: '1.0'
  contact:
    name: Audius
    url: https://audius.co
  x-logo:
    url: https://audius.co/favicons/favicon.ico
servers:
- url: https://api.audius.co/v1
  description: Production
tags:
- name: playlists
  description: Playlist related operations
paths:
  /playlists:
    get:
      tags:
      - playlists
      description: Gets a list of playlists by ID, UPC, or permalink
      operationId: Get Bulk Playlists
      security:
      - {}
      - OAuth2:
        - read
      parameters:
      - name: user_id
        in: query
        description: The user ID of the user making the request
        schema:
          type: string
      - name: id
        in: query
        description: The ID of the playlist(s)
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: permalink
        in: query
        description: The permalink(s) of the playlist(s)
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: upc
        in: query
        description: The UPC of the playlist(s)
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/playlist_response'
        '400':
          description: Bad request
          content: {}
        '500':
          description: Server error
          content: {}
    post:
      tags:
      - playlists
      description: Creates a new playlist or album
      operationId: Create Playlist
      security:
      - BearerAuth: []
      - BasicAuth: []
      - OAuth2:
        - write
      parameters:
      - name: user_id
        in: query
        description: The user ID of the user making the request
        required: true
        schema:
          type: string
      requestBody:
        x-codegen-request-body-name: metadata
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_playlist_request_body'
      responses:
        '201':
          description: Playlist created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_playlist_response'
        '400':
          description: Bad request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '500':
          description: Server error
          content: {}
  /playlists/search:
    get:
      tags:
      - playlists
      description: Search for a playlist
      operationId: Search Playlists
      parameters:
      - name: offset
        in: query
        description: The number of items to skip. Useful for pagination (page number * limit)
        schema:
          type: integer
      - name: limit
        in: query
        description: The number of items to fetch
        schema:
          type: integer
      - name: query
        in: query
        description: The search query
        schema:
          type: string
      - name: genre
        in: query
        description: The genres to filter by
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: sort_method
        in: query
        description: The sort method
        schema:
          type: string
          enum:
          - relevant
          - popular
          - recent
      - name: mood
        in: query
        description: The moods to filter by
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: includePurchaseable
        in: query
        description: Whether or not to include purchaseable content
        schema:
          type: string
      - name: has_downloads
        in: query
        description: Only include tracks that have downloads in the track results
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/playlist_search_result'
        '400':
          description: Bad request
          content: {}
        '500':
          description: Server error
          content: {}
  /playlists/trending:
    get:
      tags:
      - playlists
      description: Returns trending playlists for a time period
      operationId: Get Trending Playlists
      security:
      - {}
      - OAuth2:
        - read
      parameters:
      - name: offset
        in: query
        description: The number of items to skip. Useful for pagination (page number * limit)
        schema:
          type: integer
      - name: limit
        in: query
        description: The number of items to fetch
        schema:
          type: integer
      - name: user_id
        in: query
        description: The user ID of the user making the request
        schema:
          type: string
      - name: time
        in: query
        description: Calculate trending over a specified time range
        schema:
          type: string
          enum:
          - week
          - month
          - year
          - allTime
      - name: type
        in: query
        description: The type of content to filter by
        schema:
          type: string
          default: playlist
          enum:
          - playlist
          - album
      - name: omit_tracks
        in: query
        description: Whether to omit tracks from the response
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trending_playlists_response'
        '400':
          description: Bad request
          content: {}
        '500':
          description: Server error
          content: {}
  /playlists/{playlist_id}:
    get:
      tags:
      - playlists
      description: Get a playlist by ID
      operationId: Get Playlist
      security:
      - {}
      - OAuth2:
        - read
      parameters:
      - name: playlist_id
        in: path
        description: A Playlist ID
        required: true
        schema:
          type: string
      - name: user_id
        in: query
        description: The user ID of the user making the request
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/playlist_response'
    put:
      tags:
      - playlists
      description: Updates an existing playlist or album
      operationId: Update Playlist
      security:
      - BearerAuth: []
      - BasicAuth: []
      - OAuth2:
        - write
      parameters:
      - name: playlist_id
        in: path
        description: A Playlist ID
        required: true
        schema:
          type: string
      - name: user_id
        in: query
        description: The user ID of the user making the request
        required: true
        schema:
          type: string
      requestBody:
        x-codegen-request-body-name: metadata
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_playlist_request_body'
      responses:
        '200':
          description: Playlist updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/write_response'
        '400':
          description: Bad request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '404':
          description: Playlist not found
          content: {}
        '500':
          description: Server error
          content: {}
    delete:
      tags:
      - playlists
      description: Deletes a playlist or album
      operationId: Delete Playlist
      security:
      - BearerAuth: []
      - BasicAuth: []
      - OAuth2:
        - write
      parameters:
      - name: playlist_id
        in: path
        description: A Playlist ID
        required: true
        schema:
          type: string
      - name: user_id
        in: query
        description: The user ID of the user making the request
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Playlist deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/write_response'
        '401':
          description: Unauthorized
          content: {}
        '404':
          description: Playlist not found
          content: {}
        '500':
          description: Server error
          content: {}
  /playlists/{playlist_id}/access-info:
    get:
      tags:
      - playlists
      description: Gets the information necessary to access the playlist and what access the given user has.
      operationId: Get Playlist Access Info
      security:
      - {}
      - OAuth2:
        - read
      parameters:
      - name: playlist_id
        in: path
        description: A Playlist ID
        required: true
        schema:
          type: string
      - name: user_id
        in: query
        description: The user ID of the user making the request
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/access_info_response'
  /playlists/{playlist_id}/tracks:
    get:
      tags:
      - playlists
      description: Fetch tracks within a playlist.
      operationId: Get Playlist Tracks
      parameters:
      - name: playlist_id
        in: path
        description: A Playlist ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/playlist_tracks_response'
        '400':
          description: Bad request
          content: {}
        '500':
          description: Server error
          content: {}
  /playlists/{playlist_id}/favorites:
    post:
      tags:
      - playlists
      description: Favorite a playlist
      operationId: Favorite Playlist
      security:
      - BearerAuth: []
      - BasicAuth: []
      - OAuth2:
        - write
      parameters:
      - name: playlist_id
        in: path
        description: A Playlist ID
        required: true
        schema:
          type: string
      - name: user_id
        in: query
        description: The user ID of the user making the request
        required: true
        schema:
          type: string
      requestBody:
        required: false
        x-codegen-request-body-name: metadata
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/favorite_request_body'
      responses:
        '200':
          description: Playlist favorited successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/write_response'
        '401':
          description: Unauthorized
          content: {}
        '404':
          description: Playlist not found
          content: {}
        '500':
          description: Server error
          content: {}
    delete:
      tags:
      - playlists
      description: Unfavorite a playlist
      operationId: Unfavorite Playlist
      security:
      - BearerAuth: []
      - BasicAuth: []
      - OAuth2:
        - write
      parameters:
      - name: playlist_id
        in: path
        description: A Playlist ID
        required: true
        schema:
          type: string
      - name: user_id
        in: query
        description: The user ID of the user making the request
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Playlist unfavorited successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/write_response'
        '401':
          description: Unauthorized
          content: {}
        '404':
          description: Playlist not found
          content: {}
        '500':
          description: Server error
          content: {}
    get:
      tags:
      - playlists
      description: Get users that favorited a playlist
      operationId: Get Users From Playlist Favorites
      security:
      - {}
      - OAuth2:
        - read
      parameters:
      - name: playlist_id
        in: path
        description: A Playlist ID
        required: true
        schema:
          type: string
      - name: offset
        in: query
        description: The number of items to skip. Useful for pagination (page number * limit)
        schema:
          type: integer
      - name: limit
        in: query
        description: The number of items to fetch
        schema:
          type: integer
      - name: user_id
        in: query
        description: The user ID of the user making the request
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/following_response'
        '400':
          description: Bad request
          content: {}
        '500':
          description: Server error
          content: {}
  /playlists/{playlist_id}/reposts:
    post:
      tags:
      - playlists
      description: Repost a playlist
      operationId: Repost Playlist
      security:
      - BearerAuth: []
      - BasicAuth: []
      - OAuth2:
        - write
      parameters:
      - name: playlist_id
        in: path
        description: A Playlist ID
        required: true
        schema:
          type: string
      - name: user_id
        in: query
        description: The user ID of the user making the request
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/repost_request_body'
      responses:
        '200':
          description: Playlist reposted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/write_response'
        '401':
          description: Unauthorized
          content: {}
        '404':
          description: Playlist not found
          content: {}
        '500':
          description: Server error
          content: {}
    delete:
      tags:
      - playlists
      description: Unrepost a playlist
      operationId: Unrepost Playlist
      security:
      - BearerAuth: []
      - BasicAuth: []
      - OAuth2:
        - write
      parameters:
      - name: playlist_id
        in: path
        description: A Playlist ID
        required: true
        schema:
          type: string
      - name: user_id
        in: query
        description: The user ID of the user making the request
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Playlist unreposted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/write_response'
        '401':
          description: Unauthorized
          content: {}
        '404':
          description: Playlist not found
          content: {}
        '500':
          description: Server error
          content: {}
    get:
      tags:
      - playlists
      description: Get users that reposted a playlist
      operationId: Get Users From Playlist Reposts
      security:
      - {}
      - OAuth2:
        - read
      parameters:
      - name: playlist_id
        in: path
        description: A Playlist ID
        required: true
        schema:
          type: string
      - name: offset
        in: query
        description: The number of items to skip. Useful for pagination (page number * limit)
        schema:
          type: integer
      - name: limit
        in: query
        description: The number of items to fetch
        schema:
          type: integer
      - name: user_id
        in: query
        description: The user ID of the user making the request
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/following_response'
        '400':
          description: Bad request
          content: {}
        '500':
          description: Server error
          content: {}
  /playlists/{playlist_id}/shares:
    post:
      tags:
      - playlists
      description: Record a playlist share event
      operationId: Share Playlist
      security:
      - BearerAuth: []
      - BasicAuth: []
      - OAuth2:
        - write
      parameters:
      - name: playlist_id
        in: path
        description: A Playlist ID
        required: true
        schema:
          type: string
      - name: user_id
        in: query
        description: The user ID of the user making the request
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Playlist share recorded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/write_response'
        '401':
          description: Unauthorized
          content: {}
        '404':
          description: Playlist not found
          content: {}
        '500':
          description: Server error
          content: {}
  /playlists/trending/{version}:
    get:
      tags:
      - playlists
      description: Returns trending playlists for a time period based on the given trending version
      operationId: Get Trending Playlists With Version
      security:
      - {}
      - OAuth2:
        - read
      parameters:
      - name: version
        in: path
        description: The strategy version of trending to use
        required: true
        schema:
          type: string
      - name: offset
        in: query
        description: The number of items to skip. Useful for pagination (page number * limit)
        schema:
          type: integer
      - name: limit
        in: query
        description: The number of items to fetch
        schema:
          type: integer
      - name: user_id
        in: query
        description: The user ID of the user making the request
        schema:
          type: string
      - name: time
        in: query
        description: Calculate trending over a specified time range
        schema:
          type: string
          enum:
          - week
          - month
          - year
          - allTime
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/trending_playlists_response'
        '400':
          description: Bad request
          content: {}
        '500':
          description: Server error
          content: {}
components:
  schemas:
    access:
      required:
      - download
      - stream
      type: object
      properties:
        stream:
          type: boolean
        download:
          type: boolean
    access_gate:
      oneOf:
      - $ref: '#/components/schemas/tip_gate'
      - $ref: '#/components/schemas/follow_gate'
      - $ref: '#/components/schemas/purchase_gate'
      - $ref: '#/components/schemas/token_gate'
    playlist_search_result:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/playlist'
    remix:
      required:
      - has_remix_author_reposted
      - has_remix_author_saved
      - parent_track_id
      - user
      type: object
      properties:
        parent_track_id:
          type: string
        user:
          $ref: '#/components/schemas/user'
        has_remix_author_reposted:
          type: boolean
        has_remix_author_saved:
          type: boolean
    track:
      required:
      - access
      - artwork
      - blocknumber
      - comment_count
      - cover_art_sizes
      - created_at
      - download
      - duration
      - favorite_count
      - field_visibility
      - followee_favorites
      - followee_reposts
      - genre
      - has_current_user_reposted
      - has_current_user_saved
      - id
      - is_available
      - is_delete
      - is_download_gated
      - is_downloadable
      - is_original_available
      - is_owned_by_user
      - is_scheduled_release
      - is_stream_gated
      - is_unlisted
      - permalink
      - play_count
      - preview
      - remix_of
      - repost_count
      - route_id
      - stream
      - title
      - track_segments
      - updated_at
      - user
      - user_id
      type: object
      properties:
        artwork:
          $ref: '#/components/schemas/track_artwork'
        description:
          type: string
        genre:
          type: string
        id:
          type: string
        track_cid:
          type: string
        preview_cid:
          type: string
        orig_file_cid:
          type: string
        orig_filename:
          type: string
        is_original_available:
          type: boolean
        mood:
          type: string
        release_date:
          type: string
          format: date
        remix_of:
          $ref: '#/components/schemas/remix_parent'
        repost_count:
          type: integer
        favorite_count:
          type: integer
        comment_count:
          type: integer
        tags:
          type: string
        title:
          type: string
        user:
          $ref: '#/components/schemas/user'
        duration:
          type: integer
        is_downloadable:
          type: boolean
        play_count:
          type: integer
        permalink:
          type: string
        is_streamable:
          type: boolean
        ddex_app:
          type: string
        playlists_containing_track:
          type: array
          items:
            type: integer
        pinned_comment_id:
          type: integer
        album_backlink:
          $ref: '#/components/schemas/album_backlink'
        access:
          type: object
          description: Describes what access the given user has
          allOf:
          - $ref: '#/components/schemas/access'
        blocknumber:
          type: integer
          description: The blocknumber this track was last updated
        create_date:
          type: string
        cover_art_sizes:
          type: string
        cover_art_cids:
          $ref: '#/components/schemas/cover_art'
        created_at:
          type: string
        credits_splits:
          type: string
        isrc:
          type: string
        license:
          type: string
        iswc:
          type: string
        field_visibility:
          $ref: '#/components/schemas/field_visibility'
        followee_reposts:
          type: array
          items:
            $ref: '#/components/schemas/repost'
        has_current_user_reposted:
          type: boolean
        is_scheduled_release:
          type: boolean
        is_unlisted:
          type: boolean
        has_current_user_saved:
          type: boolean
        followee_favorites:
          type: array
          items:
            $ref: '#/components/schemas/favorite'
        route_id:
          type: string
        stem_of:
          $ref: '#/components/schemas/stem_parent'
        track_segments:
          type: array
          items:
            $ref: '#/components/schemas/track_segment'
        updated_at:
          type: string
        user_id:
          type: string
        is_delete:
          type: boolean
        cover_art:
          type: string
        is_available:
          type: boolean
        ai_attribution_user_id:
          type: integer
        allowed_api_keys:
          type: array
          items:
            type: string
        audio_upload_id:
          type: string
        preview_start_seconds:
          type: number
        bpm:
          type: number
        is_custom_bpm:
          type: boolean
        musical_key:
          type: string
        is_custom_musical_key:
          type: boolean
        audio_analysis_error_count:
          type: integer
        comments_disabled:
          type: boolean
        ddex_release_ids:
          type: object
          properties: {}
        artists:
          type: array
          items:
            type: object
            properties: {}
        resource_contributors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ddex_resource_contributor'
        indirect_resource_contributors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ddex_resource_contributor'
        rights_controller:
          $ref: '#/components/schemas/ddex_rights_controller'
        copyright_line:
          allOf:
          - $ref: '#/components/schemas/ddex_copyright'
        producer_copyright_line:
          allOf:
          - $ref: '#/components/schemas/ddex_copyright'
        parental_warning_type:
          type:
          - string
          - 'null'
        is_stream_gated:
          type: boolean
          description: Whether or not the owner has restricted streaming behind an access gate
        access_authorities:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Wallet addresses that can sign to authorize stream access (programmable distribution). When empty or omitted, the track is public and validator/creator nodes can serve it.
        stream_conditions:
          type: object
          description: How to unlock stream access to the track
          allOf:
          - $ref: '#/components/schemas/access_gate'
        is_download_gated:
          type: boolean
          description: Whether or not the owner has restricted downloading behind an access gate
        download_conditions:
          type: object
          description: How to unlock the track download
          allOf:
          - $ref: '#/components/schemas/access_gate'
        cover_original_song_title:
          type: string
        cover_original_artist:
          type: string
        is_owned_by_user:
          type: boolean
          description: Indicates whether the track is owned by the user for MRI sake
        stream:
          $ref: '#/components/schemas/url_with_mirrors'
        download:
          $ref: '#/components/schemas/url_with_mirrors'
        preview:
          $ref: '#/components/schemas/url_with_mirrors'
    favorite_request_body:
      type: object
      description: Optional metadata for favorite/save operations
      properties:
        is_save_of_repost:
          type: boolean
          description: Set to true when favoriting a reposted item (used for notifications)
    payment_split:
      required:
      - user_id
      - percentage
      type: object
      properties:
        user_id:
          type: integer
          example: 1234
        percentage:
          type: number
    field_visibility:
      required:
      - genre
      - mood
      - play_count
      - remixes
      - share
      - tags
      type: object
      properties:
        mood:
          type: boolean
        tags:
          type: boolean
        genre:
          type: boolean
        share:
          type: boolean
        play_count:
          type: boolean
        remixes:
          type: boolean
    extended_purchase_gate:
      required:
      - usdc_purchase
      type: object
      properties:
        usdc_purchase:
          type: object
          description: Must pay the total price and split to the given addresses to unlock
          allOf:
          - $ref: '#/components/schemas/extended_usdc_gate'
    extended_token_gate:
      required:
      - token_mint
      - token_amount
      type: object
      properties:
        token_mint:
          type: string
          description: The mint of the token needed to unlock
        token_amount:
          type: integer
          description: The amount of the token needed to unlock
    create_playlist_request_body:
      type: object
      required:
      - playlist_name
      properties:
        playlist_id:
          type: string
          description: Optional playlist ID (will be generated if not provided)
          example: x5pJ3Az
        playlist_name:
          type: string
          minLength: 1
          description: Playlist or album name
          example: My New Playlist
        description:
          type: string
          description: Playlist description
          maxLength: 1000
        is_private:
          type: boolean
          description: Whether the playlist is private
        is_album:
          type: boolean
          description: Whether this is an album
        genre:
          $ref: '#/components/schemas/genre'
        mood:
          allOf:
          - $ref: '#/components/schemas/mood'
        tags:
          type: string
          description: Comma-separated tags
        license:
          type: string
          description: License type
        upc:
          type: string
          description: Universal Product Code (for albums)
        release_date:
          type: string
          format: date
          description: Release date
        playlist_image_sizes_multihash:
          type: string
          description: CID for the playlist cover art
        playlist_contents:
          type: array
          description: Array of tracks in the playlist
          items:
            $ref: '#/components/schemas/playlist_added_timestamp'
        is_stream_gated:
          type:
          - boolean
          - 'null'
          description: Whether streaming is restricted behind an access gate
        is_scheduled_release:
          type:
          - boolean
          - 'null'
          description: Whether the playlist/album is a scheduled release
        stream_conditions:
          allOf:
          - $ref: '#/components/schemas/access_gate'
        ddex_app:
          type: string
          description: DDEX application identifier
        ddex_release_ids:
          type:
          - object
          - 'null'
          additionalProperties:
            type: string
          description: D

# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/audius/refs/heads/main/openapi/audius-playlists-api-openapi.yml