openapi: 3.0.1
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:
    playlist_library:
      type: object
      properties:
        contents:
          type: array
          items:
            type: object
            properties: {}
    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
          nullable: true
          items:
            $ref: '#/components/schemas/ddex_resource_contributor'
        indirect_resource_contributors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ddex_resource_contributor'
        rights_controller:
          nullable: true
          $ref: '#/components/schemas/ddex_rights_controller'
        copyright_line:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/ddex_copyright'
        producer_copyright_line:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/ddex_copyright'
        parental_warning_type:
          type: string
          nullable: true
        is_stream_gated:
          type: boolean
          description: Whether or not the owner has restricted streaming behind an access gate
        access_authorities:
          type: array
          nullable: true
          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'
    access:
      required:
      - download
      - stream
      type: object
      properties:
        stream:
          type: boolean
        download:
          type: boolean
    album_backlink:
      required:
      - permalink
      - playlist_id
      - playlist_name
      type: object
      properties:
        playlist_id:
          type: integer
        playlist_name:
          type: string
        permalink:
          type: string
    extended_payment_split:
      required:
      - amount
      - payout_wallet
      - percentage
      type: object
      properties:
        user_id:
          type: integer
          example: 1234
        percentage:
          type: number
        eth_wallet:
          type: string
        payout_wallet:
          type: string
        amount:
          type: integer
    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
    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)
    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/usdc_gate'
    playlist_search_result:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/playlist'
    track_access_info:
      required:
      - blocknumber
      - user_id
      type: object
      properties:
        access:
          type: object
          description: Describes what access the given user has
          allOf:
          - $ref: '#/components/schemas/access'
        user_id:
          type: string
          description: The user ID of the owner of this track
        blocknumber:
          type: integer
          description: The blocknumber this track was last updated
        is_stream_gated:
          type: boolean
          description: Whether or not the owner has restricted streaming behind an access gate
        stream_conditions:
          type: object
          description: How to unlock stream access to the track
          allOf:
          - $ref: '#/components/schemas/extended_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/extended_access_gate'
    create_playlist_response:
      type: object
      properties:
        transaction_hash:
          type: string
          description: The blockchain transaction hash
        block_hash:
          type: string
          description: The blockchain block hash
        block_number:
          type: integer
          format: int64
          description: The blockchain block number/height
        playlist_id:
          type: string
          description: The ID of the created playlist
    payment_split:
      required:
      - user_id
      - percentage
      type: object
      properties:
        user_id:
          type: integer
          example: 1234
        percentage:
          type: number
    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
    version_metadata:
      required:
      - service
      - version
      type: object
      properties:
        service:
          type: string
        version:
          type: string
    ddex_resource_contributor:
      type: object
      required:
      - name
      - roles
      properties:
        name:
          type: string
          minLength: 1
          description: Contributor name
        roles:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
          description: Contributor roles
        sequence_number:
          type: integer
          minimum: 0
          description: Sequence number for ordering
    following_response:
      required:
      - latest_chain_block
      - latest_chain_slot_plays
      - latest_indexed_block
      - latest_indexed_slot_plays
      - signature
      - timestamp
      - version
      type: object
      properties:
        latest_chain_block:
          type: integer
        latest_indexed_block:
          type: integer
        latest_chain_slot_plays:
          type: integer
        latest_indexed_slot_plays:
          type: integer
        signature:
          type: string
        timestamp:
          type: string
        version:
          $ref: '#/components/schemas/version_metadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/user'
    url_with_mirrors:
      required:
      - mirrors
      type: object
      properties:
        url:
          type: string
        mirrors:
          type: array
          items:
            type: string
    genre:
      type: string
      description: Music genre
      enum:
      - Electronic
      - Rock
      - Metal
      - Alternative
      - Hip-Hop/Rap
      - Experimental
      - Punk
      - Folk
      - Pop
      - Ambient
      - Soundtrack
      - World
      - Jazz
      - Acoustic
      - Funk
      - R&B/Soul
      - Devotional
      - Classical
      - Reggae
      - Podcasts
      - Country
      - Spoken Word
      - Comedy
      - Blues
      - Kids
      - Audiobooks
      - Latin
      - Lo-Fi
      - Hyperpop
      - Dancehall
      - Techno
      - Trap
      - House
      - Tech House
      - Deep House
      - Disco
      - Electro
      - Jungle
      - Progressive House
      - Hardstyle
      - Glitch Hop
      - Trance
      - Future Bass
      - Future House
      - Tropical House
      - Downtempo
      - Drum & Bass
      - Dubstep
      - Jersey Club
      - Vaporwave
      - Moombahton
    playlist:
      required:
      - access
      - added_timestamps
      - blocknumber
      - created_at
      - favorite_count
      - followee_favorites
      - followee_reposts
      - has_current_user_reposted
      - has_current_user_saved
      - id
      - is_album
      - is_delete
      - is_image_autogenerated
      - is_private
      - is_scheduled_release
      - is_stream_gated
      - permalink
      - playlist_contents
      - playlist_name
      - repost_count
      - total_play_count
      - track_count
      - updated_at
      - user
      - user_id
      type: object
      properties:
        artwork:
          $ref: '#/components/schemas/playlist_artwork'
        description:
          type: string
        permalink:
          type: string
        id:
          type: string
        is_album:
          type: boolean
        is_image_autogenerated:
          type: boolean
        playlist_name:
          type: string
        playlist_contents:
          type: array
          items:
            $ref: '#/components/schemas/playlist_added_timestamp'
        repost_count:
          type: integer
        favorite_count:
          type: integer
        total_play_count:
          type: integer
        user:
          $ref: '#/components/schemas/user'
        ddex_app:
          type: string
        access:
          $ref: '#/components/schemas/access'
        upc:
          type: string
        track_count:
          type: integer
        blocknumber:
          type: integer
        created_at:
          type: string
        followee_reposts:
          type: array
          items:
            $ref: '#/components/schemas/repost'
        followee_favorites:
          type: array
          items:
            $ref: '#/components/schemas/favorite'
        has_current_user_reposted:
          type: boolean
        has_current_user_saved:
          type: boolean
        is_delete:
          type: boolean
        is_private:
          type: boolean
        updated_at:
          type: string
        added_timestamps:
          type: array
          description: DEPRECATED. Use playlist_contents instead.
          items:
            $ref: '#/components/schemas/playlist_added_timestamp'
        user_id:
          type: string
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/track'
        cover_art:
          type: string
        cover_art_sizes:
          type: string
        cover_art_cids:
          $ref: '#/components/schemas/playlist_artwork'
        is_stream_gated:
          type: boolean
        stream_conditions:
          type: object
          description: How to unlock stream access to the track
          allOf:
          - $ref: '#/components/schemas/access_gate'
        is_scheduled_release:
          type: boolean
        release_date:
          type: string
          format: date
        ddex_release_ids:
          type: object
          properties: {}
        artists:
          type: array
          items:
            type: object
            properties: {}
        copyright_line:
          type: object
          properties: {}
        producer_copyright_line:
          type: object
          properties: {}
        parental_warning_type:
          type: string
          nullable: true
    playlist_response:
      required:
      - latest_chain_block
      - latest_chain_slot_plays
      - latest_indexed_block
      - latest_indexed_slot_plays
      - signature
      - timestamp
      - version
      type: object
      properties:
        latest_chain_block:
          type: integer
        latest_indexed_block:
          type: integer
        latest_chain_slot_plays:
          type: integer
        latest_indexed_slot_plays:
          type: integer
        signature:
          type: string
        timestamp:
          type: string
        version:
          $ref: '#/components/schemas/version_metadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/playlist'
    profile_picture:
      type: object
      properties:
        150x150:
          type: string
        480x480:
          type: string
        1000x1000:
          type: string
        mirrors:
          type: array
          items:
            type: string
    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_usdc_gate:
      required:
      - price
      - splits
      type: object
      properties:
        price:
          type: integer
        splits:
          type: array
          items:
            $ref: '#/components/schemas/extended_payment_split'
    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
    write_response:
      type: object
      properties:
        transaction_hash:
          type: string
          description: The blockchain transaction hash
        block_hash:
          type: string
          description: The blockchain block hash
        block_number:
          type: integer
          format: int64
          description: The blockchain block number/height
    remix_parent:
      type: object
      properties:
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/remix'
    favorite:
      required:
      - created_at
      - favorite_item_id
      - favorite_type
      - user_id
      type: object
      properties:
        favorite_item_id:
          type: string
        favorite_type:
          type: string
        user_id:
          type: string
        created_at:
          type: string
    playlist_artwork:
      type: object
      properties:
        150x150:
          type: string
        480x480:
          type: string
        1000x1000:
          type: string
        mirrors:
          type: array
          items:
            type: string
    track_artwork:
      type: object
      properties:
        150x150:
          type: string
        480x480:
          type: string
        1000x1000:
          type: string
        mirrors:
          type: array
          items:
            type: string
    cover_photo:
      type: object
      properties:
        640x:
          type: string
        2000x:
          type: string
        mirrors:
          type: array
          items:
            type: string
    access_gate:
      oneOf:
      - $ref: '#/components/schemas/tip_gate'
      - $ref: '#/components/schemas/follow_gate'
      - $ref: '#/components/schemas/purchase_gate'
      - $ref: '#/components/schemas/token_gate'
    user:
      required:
      - album_count
      - allow_ai_attribution
      - artist_coin_badge
      - associated_sol_wallets_balance
      - associated_wallets_balance
      - balance
      - blocknumber
      - created_at
      - current_user_followee_follow_count
      - does_current_user_follow
      - does_current_user_subscribe
      - does_follow_current_user
      - erc_wallet
      - followee_count
      - follower_count
      - handle
      - handle_lc
      - has_collectibles
      - id
      - is_available
      - is_deactivated
      - is_storage_v2
      - is_verified
      - name
      - playlist_count
      - repost_count
      - spl_wallet
      - spl_usdc_wallet
      - supporter_count
      - supporting_count
      - total_audio_balance
      - total_balance
      - track_count
      - updated_at
      - verified_with_instagram
      - verified_with_tiktok
      - verified_with_twitter
      - wallet
      - waudio_balance
      type: object
      properties:
        album_count:
          type: integer
        artist_pick_track_id:
          type: string
        artist_coin_badge:
          type: object
          properties:
            mint:
              type: string
            logo_uri:
              type: string
            banner_image_url:
              type: string
            ticker:
              type: string
              description: The coin symbol/ticker
        coin_flair_mint:
          type: string
        bio:
          type: string
        cover_photo:
          $ref: '#/components/schemas/cover_photo'
        followee_count:
          type: integer
        follower_count:
          type: integer
        handle:
          type: string
        id:
          type: string
        is_verified:
          type: boolean
        twitter_handle:
          type: string
        instagram_handle:
          type: string
        tiktok_handle:
          type: string
        verified_with_twitter:
          type: boolean
        verified_with_instagram:
          type: boolean
        verified_with_tiktok:
          type: boolean
        website:
          type: string
        donation:
          type: string
        location:
          type: string
        name:
          type: string
        playlist_count:
          type: integer
        profile_picture:
          $ref: '#/components/schemas/profile_picture'
        repost_count:
          type: integer
        track_count:
          type: integer
        is_deactivated:
          type: boolean
        is_available:
          type: boolean
        erc_wallet:
          type: string
        spl_wallet:
          type: string
        spl_usdc_wallet:
          type: string
        spl_usdc_payout_wallet:
          type: string
        supporter_count:
          type: integer
        supporting_count:
          type: integer
        total_audio_balance:
          type: integer
        wallet:
          type: string
          description: The user's Ethereum wallet address for their account
        balance:
          type: string
        associated_wallets_balance:
          type: string
        total_balance:
          type: string
        waudio_balance:
          type: string
        associated_sol_wallets_balance:
          type: string
        blocknumber:
          type: integer
        created_at:
          type: string
        is_storage_v2:
          type: boolean
        creator_node_endpoint:
          type: string
        current_user_followee_follow_count:
          type: integer
        does_current_user_follow:
          type: boolean
        does_current_user_subscribe:
          type: boolean
        does_follow_current_user:
          type: boolean
        handle_lc:
          type: string
        updated_at:
          type: string
        cover_photo_sizes:
          type: string
        cover_photo_cids:
          $ref: '#/components/schemas/cover_photo'
        cover_photo_legacy:
          type: string
        profile_picture_sizes:
          type: string
        profile_picture_cids:
          $ref: '#/components/schemas/profile_picture'
        profile_picture_legacy:
          type: string
        has_collectibles:
          type: boolean
        playlist_library:
          $ref: '#/components/schemas/playlist_library'
        allow_ai_attribution:
          type: boolean
        profile_type:
          type: string
    playlist_tracks_response:
      required:
      - latest_chain_block
      - latest_chain_slot_plays
      - latest_indexed_block
      - latest_indexed_slot_plays
      - signature
      - timestamp
      - version
      type: object
      properties:
        latest_chain_block:
          type: integer
        latest_indexed_block:
          type: integer
        latest_chain_slot_plays:
          type: integer
        latest_indexed_slot_plays:
          type: integer
        signature:
          type: string
        timestamp:
          type: string
        version:
          $ref: '#/components/schemas/version_metadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/track'
    cover_art:
      type: object
      properties:
        150x150:
          type: string
        480x480:
          type: string
        1000x1000:
          type: string
        mirrors:
          type: array
          items:
            type: string
    follow_gate:
      required:
      - follow_user_id
      type: object
      properties:
        follow_user_id:
          type: integer
          description: Must follow the given user ID 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
          nullable: true
          description: Whether streaming is restricted behind an access gate
        is_scheduled_release:
          type: boolean
          nullable: true
          description: Whether the playlist/album is a scheduled release
        stream_conditions:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/access_gate'
        ddex_app:
          type: string
          description: DDEX application identifier
        ddex_release_ids:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: DDEX release identifiers
        artists:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ddex_resource_contributor'
          description: DDEX resource contributors / artists
        copyright_line:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/ddex_copyright'
          description: DDEX copyright line
        producer_copyright_line:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/ddex_copyright'
          description: DDEX producer copyright line
        parental_warning_type:
          type: string
          nullable: true
          description: Parental warning type
        is_image_autogenerated:
          type: boolean
          nullable: true
          description: Whether the image is autogenerated
    repost_request_body:
      type: object
      description: Optional metadata for repost operations
      properties:
        is_repost_of_repost:
          type: boolean
          description: Set to true when reposting an item that was reposted (used for notifications)
    mood:
      type: string
      description: Music mood
      enum:
      - Peaceful
      - Romantic
      - Sentimental
      - Tender
      - Easygoing
      - Yearning
      - Sophisticated
      - Sensual
      - Cool
      - Gritty
      - Melancholy
      - Serious
      - Brooding
      - Fiery
      - Defiant
      - Aggressive
      - Rowdy
      - Excited
      - Energizing
      - Empowering
      - Stirring
      - Upbeat
      - Other
    ddex_rights_controller:
      type: object
      description: DDEX rights controller
      required:
      - name
      - roles
      properties:
        name:
          type: string
          minLength: 1
        roles:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
        rights_share_unknown:
          type: string
          description: Optional
    repost:
      required:
      - repost_item_id
      - repost_type
      - user_id
      type: object
      properties:
        repost_item_id:
          type: string
        repost_type:
          type: string
        user_id:
          type: string
    update_playlist_request_body:
      type: object
      description: Request body for updating playlist information. All fields are optional.
      properties:
        playlist_name:
          type: string
          minLength: 1
          description: Playlist or album name
        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 track IDs to include in the playlist
          items:
            $ref: '#/components/schemas/playlist_added_timestamp'
        is_stream_gated:
          type: boolean
          nullable: true
          description: Whether streaming is restricted behind an access gate
        is_scheduled_release:
          type: boolean
          nullable: true
          description: Whether the playlist/album is a scheduled release
        stream_conditions:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/access_gate'
        ddex_app:
          type: string
          description: DDEX application identifier
        ddex_release_ids:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: DDEX release identifiers
        artists:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ddex_resource_contributor'
          description: DDEX resource contributors / artists
        copyright_line:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/ddex_copyright'
          description: DDEX copyright line
        producer_copyright_line:
          nullable: true
          allOf:
          - $ref: '#/components/schemas/ddex_copyright'
          description: DDEX producer copyright line
        parental_warning_type:
          type: string
          nullable: true
          description: Parental warning type
        is_image_autogenerated:
          type: boolean
          nullable: true
          description: Whether the image is autogenerated
    playlist_added_timestamp:
      required:
      - timestamp
      - track_id
      type: object
      properties:
        metadata_timestamp:
          type: integer
          description: Optional. Metadata timestamp for when the track was added to the playlist.
        timestamp:
          type: integer
        track_id:
          type: string
    token_gate:
      required:
      - token_gate
      type: object
      properties:
        token_gate:
          type: object
          description: Must hold an NFT of the given collection to unlock
          allOf:
          - $ref: '#/components/schemas/extended_token_gate'
    tip_gate:
      required:
      - tip_user_id
      type: object
      properties:
        tip_user_id:
          type: integer
          description: Must tip the given user ID to unlock
    usdc_gate:
      required:
      - price
      - splits
      type: object
      properties:
        price:
          type: integer
          description: The price in USDC needed to unlock
        splits:
          type: array
          items:
            $ref: '#/components/schemas/payment_split'
    access_info_response:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/track_access_info'
    extended_access_gate:
      oneOf:
      - $ref: '#/components/schemas/tip_gate'
      - $ref: '#/components/schemas/follow_gate'
      - $ref: '#/components/schemas/extended_purchase_gate'
      - $ref: '#/components/schemas/token_gate'
    trending_playlists_response:
      required:
      - latest_chain_block
      - latest_chain_slot_plays
      - latest_indexed_block
      - latest_indexed_slot_plays
      - signature
      - timestamp
      - version
      type: object
      properties:
        latest_chain_block:
          type: integer
        latest_indexed_block:
          type: integer
        latest_chain_slot_plays:
          type: integer
        latest_indexed_slot_plays:
          type: integer
        signature:
          type: string
        timestamp:
          type: string
        version:
          $ref: '#/components/schemas/version_metadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/playlist'
    stem_parent:
      required:
      - category
      - parent_track_id
      type: object
      properties:
        category:
          type: string
        parent_track_id:
          type: integer
    ddex_copyright:
      type: object
      required:
      - year
      - text
      properties:
        year:
          type: string
          minLength: 4
          maxLength: 4
          description: Copyright year (4 characters)
        text:
          type: string
          minLength: 1
          description: Copyright text
    track_segment:
      required:
      - duration
      - multihash
      type: object
      properties:
        duration:
          type: number
        multihash:
          type: string
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'OAuth 2.0 Authorization Code flow with PKCE for third-party applications.


        Allows apps to authenticate users and obtain access tokens scoped to read or read+write permissions on behalf of the user.


        **Scopes:**

        - `read` — Read-only access to the user''s public and private data.

        - `write` — Read and write access, allowing mutations on behalf of the user.


        **PKCE Required:**

        All authorization code requests must include `code_challenge` and `code_challenge_method=S256` parameters.

        '
      flows:
        authorizationCode:
          authorizationUrl: /v1/oauth/authorize
          tokenUrl: /v1/oauth/token
          scopes:
            read: Read-only access to user data
            write: Read and write access on behalf of the user
    BasicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic Authentication with Ethereum private key for write operations.


        **Authentication**


        Use HTTP Basic Authentication where the password field contains your Ethereum private key:

        ```

        Authorization: Basic <base64(username:privatekey)>

        ```


        The username can be any value. The password must be your Ethereum private key in hex format (with or without 0x prefix).


        Example:

        ```

        Authorization: Basic dXNlcm5hbWU6MHgxMjM0NTY3ODkwYWJjZGVmLi4u

        ```


        **How it works:**

        1. The API decodes the Basic Auth credentials

        2. Extracts the private key from the password field

        3. Derives the Ethereum address from the private key

        4. Uses this address for authorization checks


        **Authorization**


        The derived wallet address must be either:

        - The wallet of the user being acted upon (direct ownership)

        - A wallet with an approved, non-revoked grant for the user (manager mode)

        '
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'The API bearer token or OAuth JWT token for the user.

        '
x-original-swagger-version: '2.0'