OpenAPI Specification
openapi: 3.0.1
info:
title: Audius challenges tracks 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: tracks
description: Track related operations
paths:
/tracks:
get:
tags:
- tracks
description: Gets a list of tracks using their IDs or permalinks
operationId: Get Bulk Tracks
security:
- {}
- OAuth2:
- read
parameters:
- name: user_id
in: query
description: The user ID of the user making the request
schema:
type: string
- name: permalink
in: query
description: The permalink of the track(s)
style: form
explode: true
schema:
type: array
items:
type: string
- name: id
in: query
description: The ID of the track(s)
style: form
explode: true
schema:
type: array
items:
type: string
- name: isrc
in: query
description: The ISRC code of the track(s)
style: form
explode: true
schema:
type: array
items:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/tracks_response'
post:
tags:
- tracks
description: Creates a new track
operationId: Create Track
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_track_request_body'
responses:
'201':
description: Track created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/create_track_response'
'400':
description: Bad request
content: {}
'401':
description: Unauthorized
content: {}
'500':
description: Server error
content: {}
/tracks/download_counts:
get:
tags:
- tracks
description: Gets download counts for tracks by ID. Use this instead of loading full track objects when only download counts are needed.
operationId: Get Track Download Counts
security:
- {}
- OAuth2:
- read
parameters:
- name: id
in: query
description: Track ID(s)
required: true
style: form
explode: true
schema:
type: array
items:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/track_download_counts_response'
/tracks/inspect:
get:
tags:
- tracks
summary: Inspects the details of the files for multiple tracks
description: Inspect multiple tracks
operationId: Inspect Tracks
parameters:
- name: id
in: query
description: List of track IDs to inspect
required: true
style: form
explode: true
schema:
type: array
items:
type: string
- name: original
in: query
description: Optional - if set to true inspects the original file quality
schema:
type: boolean
default: false
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/track_inspect_list'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/tracks/recent-premium:
get:
tags:
- tracks
description: Gets the most recently listed premium tracks
operationId: Get Recent Premium Tracks
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
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/tracks_response'
/tracks/recommended:
get:
tags:
- tracks
description: Get recommended tracks
operationId: Get Recommended Tracks
security:
- {}
- OAuth2:
- read
parameters:
- name: limit
in: query
description: The number of items to fetch
schema:
type: integer
- name: genre
in: query
description: Filter trending to a specified genre
schema:
type: string
- name: time
in: query
description: Calculate trending over a specified time range
schema:
type: string
enum:
- week
- month
- year
- allTime
- name: exclusion_list
in: query
description: List of track ids to exclude
style: form
explode: true
schema:
type: array
items:
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/tracks_response'
/tracks/recommended/{version}:
get:
tags:
- tracks
description: Get recommended tracks using the given trending strategy version
operationId: Get Recommended Tracks With Version
security:
- {}
- OAuth2:
- read
parameters:
- name: version
in: path
description: The strategy version of trending to use
required: true
schema:
type: string
- name: limit
in: query
description: The number of items to fetch
schema:
type: integer
- name: genre
in: query
description: Filter trending to a specified genre
schema:
type: string
- name: time
in: query
description: Calculate trending over a specified time range
schema:
type: string
enum:
- week
- month
- year
- allTime
- name: exclusion_list
in: query
description: List of track ids to exclude
style: form
explode: true
schema:
type: array
items:
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/tracks_response'
/tracks/feeling-lucky:
get:
tags:
- tracks
description: Gets random tracks found on the "Feeling Lucky" smart playlist
operationId: Get Feeling Lucky Tracks
security:
- {}
- OAuth2:
- read
parameters:
- name: user_id
in: query
description: The user ID of the user making the request
schema:
type: string
- name: limit
in: query
description: Number of tracks to fetch
schema:
type: integer
default: 10
minimum: 1
maximum: 100
- name: with_users
deprecated: true
in: query
description: Boolean to include user info with tracks
schema:
type: boolean
default: false
- name: min_followers
in: query
description: Fetch tracks from users with at least this number of followers
schema:
type: integer
minimum: 1
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/tracks_response'
'400':
description: Bad request
content: {}
/tracks/recent-comments:
get:
tags:
- tracks
description: Gets the most recent tracks with active discussion
operationId: Get Tracks With Recent Comments
security:
- {}
- OAuth2:
- read
parameters:
- name: user_id
in: query
description: The user ID of the user making the request
schema:
type: string
- name: limit
in: query
description: Number of tracks to fetch
schema:
type: integer
default: 10
minimum: 1
maximum: 100
- name: offset
in: query
description: The number of items to skip. Useful for pagination (page number * limit)
schema:
type: integer
default: 0
minimum: 0
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/tracks_response'
'400':
description: Bad request
content: {}
/tracks/most-shared:
get:
tags:
- tracks
description: Gets the most shared tracks for a given time range
operationId: Get Most Shared Tracks
security:
- {}
- OAuth2:
- read
parameters:
- name: user_id
in: query
description: The user ID of the user making the request
schema:
type: string
- name: limit
in: query
description: Number of tracks to fetch
schema:
type: integer
default: 10
minimum: 1
maximum: 100
- name: offset
in: query
description: The number of items to skip. Useful for pagination (page number * limit)
schema:
type: integer
default: 0
minimum: 0
- name: time_range
in: query
description: The time range to consider
schema:
type: string
default: week
enum:
- week
- month
- allTime
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/tracks_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/tracks/usdc-purchase:
get:
tags:
- tracks
description: Gets the top trending (most popular) USDC purchase tracks on Audius
operationId: Get Trending USDC Purchase Tracks
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: genre
in: query
description: Filter trending to a specified genre
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/tracks_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/tracks/usdc-purchase/{version}:
get:
tags:
- tracks
description: Gets the top trending (most popular) USDC purchase tracks on Audius using a given trending strategy version
operationId: Get Trending USDC Purchase Tracks 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: genre
in: query
description: Filter trending to a specified genre
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/tracks_response'
/tracks/search:
get:
tags:
- tracks
description: Search for a track or tracks
operationId: Search Tracks
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: only_downloadable
in: query
description: Return only downloadable tracks
schema:
type: string
default: 'false'
- name: includePurchaseable
in: query
description: Whether or not to include purchaseable content
schema:
type: string
- name: is_purchaseable
in: query
description: Only include purchaseable tracks and albums in the track and album results
schema:
type: string
- name: has_downloads
in: query
description: Only include tracks that have downloads in the track results
schema:
type: string
- 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: string
- name: bpm_max
in: query
description: Only include tracks that have a bpm less than or equal to
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/track_search'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/tracks/trending:
get:
tags:
- tracks
description: Gets the top 100 trending (most popular) tracks on Audius
operationId: Get Trending Tracks
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: genre
in: query
description: Filter trending to a specified genre
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/tracks_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/tracks/trending/winners:
get:
tags:
- tracks
description: Gets weekly trending winners from the trending_results table. Returns track objects for the specified week. Defaults to the most recent week with data when no week is provided.
operationId: Get Trending Winners
security:
- {}
- OAuth2:
- read
parameters:
- name: week
in: query
description: Target week in YYYY-MM-DD format. Defaults to the most recent week with data.
schema:
type: string
format: date
- 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/tracks_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/tracks/trending/{version}:
get:
tags:
- tracks
description: Gets the top 100 trending (most popular) tracks on Audius using a given trending strategy version
operationId: Get Trending Tracks 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: genre
in: query
description: Filter trending to a specified genre
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/tracks_response'
/tracks/trending/ids:
get:
tags:
- tracks
description: Gets the track IDs of the top trending tracks on Audius
operationId: Get Trending Track IDs
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: genre
in: query
description: Filter trending to a specified genre
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/trending_ids_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/tracks/trending/ids/{version}:
get:
tags:
- tracks
description: Gets the track IDs of the top trending tracks on Audius based on the given trending strategy version
operationId: Get Trending Tracks IDs With Version
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: genre
in: query
description: Filter trending to a specified genre
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/trending_ids_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/tracks/trending/underground:
get:
tags:
- tracks
description: Gets the top 100 trending underground tracks on Audius
operationId: Get Underground Trending Tracks
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
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/tracks_response'
/tracks/trending/underground/winners:
get:
tags:
- tracks
description: Gets weekly trending underground winners from the trending_results table. Returns track objects for the specified week. Defaults to the most recent week with data when no week is provided.
operationId: Get Trending Underground Winners
security:
- {}
- OAuth2:
- read
parameters:
- name: week
in: query
description: Target week in YYYY-MM-DD format. Defaults to the most recent week with data.
schema:
type: string
format: date
- 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/tracks_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/tracks/trending/underground/{version}:
get:
tags:
- tracks
description: Gets the top 100 trending underground tracks on Audius using a given trending strategy version
operationId: Get Underground Trending Tracks With Version
security:
- {}
- OAuth2:
- read
parameters:
- name: version
in: path
description: The strategy version of trending to user
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/tracks_response'
/tracks/{track_id}:
get:
tags:
- tracks
description: Gets a track by ID.
operationId: Get Track
security:
- {}
- OAuth2:
- read
parameters:
- name: track_id
in: path
description: A Track 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/track_response'
put:
tags:
- tracks
description: Updates an existing track
operationId: Update Track
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: track_id
in: path
description: A Track 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_track_request_body'
responses:
'200':
description: Track updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'400':
description: Bad request
content: {}
'401':
description: Unauthorized
content: {}
'404':
description: Track not found
content: {}
'500':
description: Server error
content: {}
delete:
tags:
- tracks
description: Deletes a track
operationId: Delete Track
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: track_id
in: path
description: A Track 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: Track deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'401':
description: Unauthorized
content: {}
'404':
description: Track not found
content: {}
'500':
description: Server error
content: {}
/tracks/{track_id}/download_count:
get:
tags:
- tracks
description: Gets the download count for a single track. Full track + all stems (parent) or stem-only (stem).
operationId: Get Track Download Count
security:
- {}
- OAuth2:
- read
parameters:
- name: track_id
in: path
description: A Track ID
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/track_download_count_response'
/tracks/{track_id}/access-info:
get:
tags:
- tracks
description: Gets the information necessary to access the track and what access the given user has.
operationId: Get Track Access Info
security:
- {}
- OAuth2:
- read
parameters:
- name: track_id
in: path
description: A Track 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'
/tracks/{track_id}/comment_count:
get:
tags:
- tracks
description: Get the comment count for a track
operationId: Get Track Comment Count
security:
- {}
- OAuth2:
- read
parameters:
- name: track_id
in: path
description: A Track ID
required: true
schema:
type: string
- name: user_id
# --- truncated at 32 KB (107 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/audius/refs/heads/main/openapi/audius-tracks-api-openapi.yml