OpenAPI Specification
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'