Audius search API

openapi: 3.0.1
info:
  title: Audius challenges search 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: search
paths:
  /search/autocomplete:
    get:
      tags:
      - search
      summary: Get Users/Tracks/Playlists/Albums that best match the search query
      description: Same as search but optimized for quicker response at the cost of some entity information.
      operationId: Search Autocomplete
      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: query
        in: query
        description: The search query
        schema:
          type: string
      - name: kind
        in: query
        description: 'The type of response, one of: all, users, tracks, playlists, or albums'
        schema:
          type: string
          default: all
          enum:
          - all
          - users
          - tracks
          - playlists
          - albums
      - name: includePurchaseable
        in: query
        description: Whether or not to include purchaseable content
        schema:
          type: boolean
      - name: genre
        in: query
        description: The genres to filter by
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: mood
        in: query
        description: The moods to filter by
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: is_verified
        in: query
        description: Only include verified users in the user results
        schema:
          type: boolean
      - name: has_downloads
        in: query
        description: Only include tracks that have downloads in the track results
        schema:
          type: boolean
      - name: is_purchaseable
        in: query
        description: Only include purchaseable tracks and albums in the track and album results
        schema:
          type: boolean
      - name: key
        in: query
        description: Only include tracks that match the musical key
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: bpm_min
        in: query
        description: Only include tracks that have a bpm greater than or equal to
        schema:
          type: number
      - name: bpm_max
        in: query
        description: Only include tracks that have a bpm less than or equal to
        schema:
          type: number
      - name: sort_method
        in: query
        description: The sort method
        schema:
          type: string
          enum:
          - relevant
          - popular
          - recent
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/search_autocomplete_response'
        '400':
          description: Bad request
          content: {}
        '500':
          description: Server error
          content: {}
  /search/full:
    get:
      tags:
      - search
      description: Get Users/Tracks/Playlists/Albums that best match the search query
      operationId: Search
      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: query
        in: query
        description: The search query
        schema:
          type: string
      - name: kind
        in: query
        description: 'The type of response, one of: all, users, tracks, playlists, or albums'
        schema:
          type: string
          default: all
          enum:
          - all
          - users
          - tracks
          - playlists
          - albums
      - name: includePurchaseable
        in: query
        description: Whether or not to include purchaseable content
        schema:
          type: boolean
      - name: genre
        in: query
        description: The genres to filter by
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: mood
        in: query
        description: The moods to filter by
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: is_verified
        in: query
        description: Only include verified users in the user results
        schema:
          type: boolean
      - name: has_downloads
        in: query
        description: Only include tracks that have downloads in the track results
        schema:
          type: boolean
      - name: is_purchaseable
        in: query
        description: Only include purchaseable tracks and albums in the track and album results
        schema:
          type: boolean
      - name: key
        in: query
        description: Only include tracks that match the musical key
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: bpm_min
        in: query
        description: Only include tracks that have a bpm greater than or equal to
        schema:
          type: number
      - name: bpm_max
        in: query
        description: Only include tracks that have a bpm less than or equal to
        schema:
          type: number
      - name: sort_method
        in: query
        description: The sort method
        schema:
          type: string
          enum:
          - relevant
          - popular
          - recent
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/search_response'
        '400':
          description: Bad request
          content: {}
        '500':
          description: Server error
          content: {}
  /search/tags:
    get:
      tags:
      - search
      description: Get Users/Tracks/Playlists/Albums that best match the provided tag
      operationId: SearchTags
      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: query
        in: query
        description: The search query
        schema:
          type: string
      - name: kind
        in: query
        description: 'The type of response, one of: all, users, tracks, playlists, or albums'
        schema:
          type: string
          default: all
          enum:
          - all
          - users
          - tracks
          - playlists
          - albums
      - name: includePurchaseable
        in: query
        description: Whether or not to include purchaseable content
        schema:
          type: boolean
      - name: genre
        in: query
        description: The genres to filter by
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: mood
        in: query
        description: The moods to filter by
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: is_verified
        in: query
        description: Only include verified users in the user results
        schema:
          type: boolean
      - name: has_downloads
        in: query
        description: Only include tracks that have downloads in the track results
        schema:
          type: boolean
      - name: is_purchaseable
        in: query
        description: Only include purchaseable tracks and albums in the track and album results
        schema:
          type: boolean
      - name: key
        in: query
        description: Only include tracks that match the musical key
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: bpm_min
        in: query
        description: Only include tracks that have a bpm greater than or equal to
        schema:
          type: number
      - name: bpm_max
        in: query
        description: Only include tracks that have a bpm less than or equal to
        schema:
          type: number
      - name: sort_method
        in: query
        description: The sort method
        schema:
          type: string
          enum:
          - relevant
          - popular
          - recent
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/search_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'
    search_model:
      required:
      - albums
      - playlists
      - tracks
      - users
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/user'
        followed_users:
          type: array
          items:
            $ref: '#/components/schemas/user'
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/search_track'
        saved_tracks:
          type: array
          items:
            $ref: '#/components/schemas/search_track'
        playlists:
          type: array
          items:
            $ref: '#/components/schemas/search_playlist'
        saved_playlists:
          type: array
          items:
            $ref: '#/components/schemas/search_playlist'
        albums:
          type: array
          items:
            $ref: '#/components/schemas/search_playlist'
        saved_albums:
          type: array
          items:
            $ref: '#/components/schemas/search_playlist'
    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
    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
    search_track:
      required:
      - access
      - artwork
      - blocknumber
      - comment_count
      - cover_art_sizes
      - created_at
      - download
      - duration
      - favorite_count
      - field_visibility
      - 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
        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'
    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'
    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
    search_playlist:
      required:
      - access
      - added_timestamps
      - blocknumber
      - created_at
      - favorite_count
      - 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
        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
  

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