OpenAPI Specification
openapi: 3.0.1
info:
title: Audius challenges users 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: users
description: User related operations
paths:
/users:
get:
tags:
- users
description: Gets a list of users by ID
operationId: Get Bulk Users
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 user(s)
style: form
explode: true
schema:
type: array
items:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/user_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
post:
tags:
- users
description: Creates a new user
operationId: Create User
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
requestBody:
x-codegen-request-body-name: metadata
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_user_request_body'
responses:
'201':
description: User created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/create_user_response'
'400':
description: Bad request
content: {}
'401':
description: Unauthorized
content: {}
'500':
description: Server error
content: {}
/users/address:
get:
tags:
- users
description: Gets User IDs from any Ethereum wallet address or Solana account address associated with their Audius account.
operationId: Get User IDs by Addresses
parameters:
- name: address
in: query
description: Wallet address
required: true
style: form
explode: true
example:
- '0x1234567890abcdef1234567890abcdef12345678'
- E2LCbKdo2L3ikt1gK6pwp1pDLuhAfHBNf6fEQXpAqrf9
schema:
type: array
items:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/user_ids_addresses_response'
/users/handle/{handle}:
get:
tags:
- users
description: Gets a single user by their handle
operationId: Get User by Handle
security:
- {}
- OAuth2:
- read
parameters:
- name: handle
in: path
description: A User handle
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/user_response_single'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/users/handle/{handle}/tracks:
get:
tags:
- users
description: Gets the tracks created by a user using the user's handle
operationId: Get Tracks by User Handle
security:
- {}
- OAuth2:
- read
parameters:
- name: handle
in: path
description: A User handle
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: sort
in: query
description: '[Deprecated] Field to sort by'
schema:
type: string
default: date
enum:
- date
- plays
- name: query
in: query
description: The filter query
schema:
type: string
- name: sort_method
in: query
description: The sort method
schema:
type: string
enum:
- title
- artist_name
- release_date
- last_listen_date
- added_date
- plays
- reposts
- saves
- most_listens_by_user
- name: sort_direction
in: query
description: The sort direction
schema:
type: string
enum:
- asc
- desc
- name: filter_tracks
in: query
description: Filter by public tracks
schema:
type: string
default: all
enum:
- all
- public
- name: Encoded-Data-Message
in: header
description: The data that was signed by the user for signature recovery
schema:
type: string
- name: Encoded-Data-Signature
in: header
description: The signature of data, used for signature recovery
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/tracks'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/users/handle/{handle}/tracks/ai_attributed:
get:
tags:
- users
description: Gets the AI generated tracks attributed to a user using the user's handle
operationId: Get AI Attributed Tracks by User Handle
security:
- {}
- OAuth2:
- read
parameters:
- name: handle
in: path
description: A User handle
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: sort
in: query
description: '[Deprecated] Field to sort by'
schema:
type: string
default: date
enum:
- date
- plays
- name: query
in: query
description: The filter query
schema:
type: string
- name: sort_method
in: query
description: The sort method
schema:
type: string
enum:
- title
- artist_name
- release_date
- last_listen_date
- added_date
- plays
- reposts
- saves
- most_listens_by_user
- name: sort_direction
in: query
description: The sort direction
schema:
type: string
enum:
- asc
- desc
- name: filter_tracks
in: query
description: Filter by public tracks
schema:
type: string
default: all
enum:
- all
- public
- name: Encoded-Data-Message
in: header
description: The data that was signed by the user for signature recovery
schema:
type: string
- name: Encoded-Data-Signature
in: header
description: The signature of data, used for signature recovery
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/tracks'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/users/search:
get:
tags:
- users
description: Search for users that match the given query
operationId: Search Users
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: is_verified
in: query
description: Only include verified users in the user results
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/user_search'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/users/verify_token:
get:
tags:
- users
description: Verify if the given jwt ID token was signed by the subject (user) in the payload
operationId: Verify ID Token
parameters:
- name: token
in: query
description: JWT to verify
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/verify_token'
'400':
description: Bad input
content: {}
'404':
description: ID token not valid
content: {}
'500':
description: Server error
content: {}
/users/{id}:
get:
tags:
- users
description: Gets a single user by their user ID
operationId: Get User
security:
- {}
- OAuth2:
- read
parameters:
- name: id
in: path
description: A User 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/user_response_single'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
put:
tags:
- users
description: Updates an existing user profile
operationId: Update User
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: id
in: path
description: A User 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_user_request_body'
responses:
'200':
description: User updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'400':
description: Bad request
content: {}
'401':
description: Unauthorized
content: {}
'404':
description: User not found
content: {}
'500':
description: Server error
content: {}
/users/{id}/albums:
get:
tags:
- users
description: Gets the albums created by a user using their user ID
operationId: Get Albums by User
security:
- {}
- OAuth2:
- read
parameters:
- name: id
in: path
description: A User 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
- name: sort_method
in: query
description: The sort method
schema:
type: string
default: recent
enum:
- recent
- popular
- name: query
in: query
description: Filter albums by name
schema:
type: string
- name: Encoded-Data-Message
in: header
description: The data that was signed by the user for signature recovery
schema:
type: string
- name: Encoded-Data-Signature
in: header
description: The signature of data, used for signature recovery
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/albums_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/users/{id}/authorized_apps:
get:
tags:
- users
description: Get the apps that user has authorized to write to their account
operationId: Get Authorized Apps
parameters:
- name: id
in: path
description: A User ID
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/authorized_apps'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/grantees/{address}/users:
get:
tags:
- users
description: Get all users who have authorized a particular grantee (developer app) identified by their wallet address. Supports pagination.
operationId: Get Grantee Users
parameters:
- name: address
in: path
description: The wallet address of the grantee (developer app)
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: is_approved
in: query
description: If true, only return users where the grant has been approved. If false, only return users where the grant was not approved. If omitted, returns all users regardless of approval status.
schema:
type: boolean
- name: is_revoked
in: query
description: If true, only return users where the grant has been revoked. Defaults to false.
schema:
type: boolean
default: false
- 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/followers_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/users/{id}/balance/history:
get:
tags:
- users
description: Get the user's historical portfolio balance data
operationId: Get User Balance History
security:
- {}
- OAuth2:
- read
parameters:
- name: id
in: path
description: A User ID
required: true
schema:
type: string
- name: start_time
in: query
description: Start time for the balance history query (ISO 8601 format). Defaults to 7 days ago.
required: false
schema:
type: string
format: date-time
- name: end_time
in: query
description: End time for the balance history query (ISO 8601 format). Defaults to now.
required: false
schema:
type: string
format: date-time
- name: granularity
in: query
description: Data granularity. 'hourly' returns hourly data points, 'daily' returns daily aggregated data. Defaults to 'hourly'.
required: false
schema:
type: string
enum:
- hourly
- daily
default: hourly
- name: user_id
in: query
description: The user ID of the user making the request
schema:
type: string
- name: Encoded-Data-Message
in: header
description: The data that was signed by the user for signature recovery
schema:
type: string
- name: Encoded-Data-Signature
in: header
description: The signature of data, used for signature recovery
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/balance_history_response'
'400':
description: Bad request
content: {}
'401':
description: Unauthorized
content: {}
'403':
description: Forbidden
content: {}
'500':
description: Server error
content: {}
/users/{id}/challenges:
get:
tags:
- users
description: Gets all challenges for the given user
operationId: Get User Challenges
parameters:
- name: id
in: path
description: A User ID
required: true
schema:
type: string
- name: show_historical
in: query
description: Whether to show challenges that are inactive but completed
schema:
type: boolean
default: false
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/get_challenges'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/users/{id}/coins:
get:
tags:
- users
description: Gets a list of the coins owned by the user and their balances
parameters:
- name: id
in: path
description: A User 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
default: 0
minimum: 0
- name: limit
in: query
description: The number of items to fetch
schema:
type: integer
default: 50
minimum: 1
maximum: 100
operationId: Get User Coins
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/user_coins_response'
/users/{id}/coins/{mint}:
get:
tags:
- users
description: Gets information about a specific coin owned by the user and their wallets
parameters:
- name: id
in: path
description: A User ID
required: true
schema:
type: string
- name: mint
in: path
description: The mint address of the coin
required: true
schema:
type: string
example: Dez1g5f3h4j5k6l7m8n9o0p1q2r3s4t5u6v7w8x9y0z
operationId: Get User Coin
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/user_coin_response'
/users/{id}/collectibles:
get:
tags:
- users
description: Get the User's indexed collectibles data
operationId: Get User Collectibles
parameters:
- name: id
in: path
description: A User ID
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/collectibles_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/users/{id}/comments:
get:
tags:
- users
description: Get user comment history
operationId: Get User Comments
security:
- {}
- OAuth2:
- read
parameters:
- name: id
in: path
description: A User 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/user_comments_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/users/{id}/connected_wallets:
get:
tags:
- users
description: Get the User's ERC and SPL connected wallets
operationId: Get connected wallets
parameters:
- name: id
in: path
description: A User ID
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/connected_wallets_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/users/{id}/favorites:
get:
tags:
- users
description: Gets a user's favorite tracks
operationId: Get User Favorites
parameters:
- name: id
in: path
description: A User ID
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/favorites_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/users/{id}/followers:
get:
tags:
- users
description: All users that follow the provided user
operationId: Get Followers
security:
- {}
- OAuth2:
- read
parameters:
- name: id
in: path
description: A User 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/followers_response'
'400':
description: Bad request
content: {}
'500':
description: Server error
content: {}
/users/{id}/follow:
post:
tags:
- users
description: Follow a user
operationId: Follow User
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: id
in: path
description: A User 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: User followed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'401':
description: Unauthorized
content: {}
'404':
description: User not found
content: {}
'500':
description: Server error
content: {}
delete:
tags:
- users
description: Unfollow a user
operationId: Unfollow User
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: id
in: path
description: A User 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: User unfollowed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'401':
description: Unauthorized
content: {}
'404':
description: User not found
content: {}
'500':
description: Server error
content: {}
/users/{id}/grants:
post:
tags:
- users
description: Create a grant (authorize an app to act on the user's behalf)
operationId: Create Grant
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: id
in: path
description: The user ID (grantor)
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_grant_request_body'
responses:
'200':
description: Grant created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'400':
description: Bad request
content: {}
'401':
description: Unauthorized
content: {}
'403':
description: Forbidden (user ID does not match)
content: {}
'500':
description: Server error
content: {}
/users/{id}/grants/{address}:
delete:
tags:
- users
description: Revoke a grant (remove app authorization)
operationId: Revoke Grant
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: id
in: path
description: The user ID (grantor)
required: true
schema:
type: string
- name: address
in: path
description: The app API key (grantee address) to revoke
required: true
schema:
type: string
responses:
'200':
description: Grant revoked successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'400':
description: Bad request
content: {}
'401':
description: Unauthorized
content: {}
'403':
description: Forbidden
content: {}
'500':
description: Server error
content: {}
/users/{id}/grants/approve:
post:
tags:
- users
description: Approve a manager request (manager approves being added by the child user)
operationId: Approve Grant
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: id
in: path
description: The user ID of the manager (grantee) approving the request
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/approve_grant_request_body'
responses:
'200':
description: Grant approved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
# --- truncated at 32 KB (187 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/audius/refs/heads/main/openapi/audius-users-api-openapi.yml