OpenAPI Specification
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
prop
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/audius/refs/heads/main/openapi/audius-playlists-api-openapi.yml