openapi: 3.0.1
info:
  title: Audius challenges explore 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: explore
  description: Explore related operations
paths:
  /explore/best-selling:
    get:
      tags:
      - explore
      summary: Get best selling tracks and playlists with related entities
      description: Get best selling tracks and/or albums with related entities
      operationId: Get Best Selling
      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: type
        in: query
        description: The type of content to filter by
        schema:
          type: string
          default: all
          enum:
          - all
          - track
          - album
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/best_selling_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
    best_selling_item:
      required:
      - content_id
      - owner_id
      - title
      type: object
      properties:
        content_id:
          type: string
        content_type:
          type: string
          example: track
          enum:
          - track
          - album
        title:
          type: string
        owner_id:
          type: string
    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
    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'
    related:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/user'
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/track'
        playlists:
          type: array
          items:
            $ref: '#/components/schemas/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
    url_with_mirrors:
      required:
      - mirrors
      type: object
      properties:
        url:
          type: string
        mirrors:
          type: array
          items:
            type: string
    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
    profile_picture:
      type: object
      properties:
        150x150:
          type: string
        480x480:
          type: string
        1000x1000:
          type: string
        mirrors:
          type: array
          items:
            type: string
    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
    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
    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
    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
    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
    best_selling_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/best_selling_item'
        related:
          $ref: '#/components/schemas/related'
    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'
    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'