OpenAPI Specification
openapi: 3.0.1
info:
title: Audius challenges comments 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: comments
description: Comment related operations
paths:
/comments/unclaimed_id:
get:
tags:
- comments
description: Gets an unclaimed blockchain comment ID
operationId: Get unclaimed comment ID
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/unclaimed_id_response'
'500':
description: Server error
content: {}
/comments:
post:
tags:
- comments
description: Creates a new comment
operationId: Create Comment
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_comment_request_body'
responses:
'201':
description: Comment created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/create_comment_response'
'400':
description: Bad request
content: {}
'401':
description: Unauthorized
content: {}
'500':
description: Server error
content: {}
/comments/{comment_id}:
get:
tags:
- comments
description: Gets a comment by ID
operationId: Get Comment
parameters:
- name: comment_id
in: path
description: A Comment ID
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/comment_response'
'500':
description: Server error
content: {}
put:
tags:
- comments
description: Updates a comment
operationId: Update Comment
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: comment_id
in: path
description: A Comment 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_comment_request_body'
responses:
'200':
description: Comment updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'401':
description: Unauthorized
content: {}
'404':
description: Comment not found
content: {}
'500':
description: Server error
content: {}
delete:
tags:
- comments
description: Deletes a comment
operationId: Delete Comment
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: comment_id
in: path
description: A Comment 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: Comment deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'401':
description: Unauthorized
content: {}
'404':
description: Comment not found
content: {}
'500':
description: Server error
content: {}
/comments/{comment_id}/react:
post:
tags:
- comments
description: React to a comment
operationId: React to Comment
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: comment_id
in: path
description: A Comment 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:
content:
application/json:
schema:
$ref: '#/components/schemas/react_comment_request_body'
required: true
x-codegen-request-body-name: metadata
responses:
'200':
description: Comment reacted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'401':
description: Unauthorized
content: {}
'404':
description: Comment not found
content: {}
'500':
description: Server error
content: {}
delete:
tags:
- comments
description: Unreact to a comment
operationId: Unreact to Comment
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: comment_id
in: path
description: A Comment 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:
content:
application/json:
schema:
$ref: '#/components/schemas/react_comment_request_body'
required: true
x-codegen-request-body-name: metadata
responses:
'200':
description: Comment unreacted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'401':
description: Unauthorized
content: {}
'404':
description: Comment not found
content: {}
'500':
description: Server error
content: {}
/comments/{comment_id}/pin:
post:
tags:
- comments
description: Pin a comment
operationId: Pin Comment
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: comment_id
in: path
description: A Comment 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:
content:
application/json:
schema:
$ref: '#/components/schemas/pin_comment_request_body'
required: true
x-codegen-request-body-name: metadata
responses:
'200':
description: Comment pinned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'401':
description: Unauthorized
content: {}
'404':
description: Comment not found
content: {}
'500':
description: Server error
content: {}
delete:
tags:
- comments
description: Unpin a comment
operationId: Unpin Comment
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: comment_id
in: path
description: A Comment 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:
content:
application/json:
schema:
$ref: '#/components/schemas/pin_comment_request_body'
required: true
x-codegen-request-body-name: metadata
responses:
'200':
description: Comment unpinned successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'401':
description: Unauthorized
content: {}
'404':
description: Comment not found
content: {}
'500':
description: Server error
content: {}
/comments/{comment_id}/report:
post:
tags:
- comments
description: Report a comment
operationId: Report Comment
security:
- BearerAuth: []
- BasicAuth: []
- OAuth2:
- write
parameters:
- name: comment_id
in: path
description: A Comment 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: Comment reported successfully
content:
application/json:
schema:
$ref: '#/components/schemas/write_response'
'401':
description: Unauthorized
content: {}
'404':
description: Comment not found
content: {}
'500':
description: Server error
content: {}
/comments/{comment_id}/replies:
get:
tags:
- comments
description: Gets replies to a parent comment
operationId: Get Comment Replies
security:
- {}
- OAuth2:
- read
parameters:
- name: comment_id
in: path
description: A Comment 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/comment_replies_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
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
unclaimed_id_response:
type: object
properties:
data:
type: string
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
update_comment_request_body:
type: object
required:
- entityType
- entityId
- body
properties:
entityType:
allOf:
- $ref: '#/components/schemas/comment_entity_type'
example: Track
entityId:
type: integer
description: ID of the entity being commented on
example: 12345
body:
type: string
description: The updated comment text
maxLength: 500
mentions:
type: array
description: Array of user IDs mentioned in the comment (max 10)
maxItems: 10
items:
type: integer
example: 67890
create_comment_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
comment_id:
type: string
description: The ID of the created comment
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
comment_mention:
required:
- handle
- user_id
type: object
properties:
user_id:
type: integer
handle:
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
write_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
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
react_comment_request_body:
type: object
required:
- entityType
- entityId
properties:
entityType:
allOf:
- $ref: '#/components/schemas/comment_entity_type'
example: Track
entityId:
type: integer
description: ID of the entity (track) being commented on
example: 12345
create_comment_request_body:
type: object
required:
- entityType
- entityId
- body
properties:
entityType:
allOf:
- $ref: '#/components/schemas/comment_entity_type'
example: Track
entityId:
type: integer
description: ID of the entity being commented on
example: 12345
body:
type: string
description: Comment text
maxLength: 500
example: Great track!
commentId:
type: integer
description: Optional ID for the comment (will be generated if not provided)
example: 98765
parentId:
type: integer
description: Parent comment ID if this is a reply
example: 54321
trackTimestampS:
type: integer
description: Timestamp in the track where the comment was made (in seconds)
minimum: 0
mentions:
type: array
description: Array of user IDs mentioned in the comment (max 10)
maxItems: 10
items:
type: integer
example: 67890
cover_photo:
type: object
properties:
640x:
type: string
2000x:
type: string
mirrors:
type: array
items:
type: string
comment_replies_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/reply_comment'
related:
$ref: '#/components/schemas/related'
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
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/audius/refs/heads/main/openapi/audius-comments-api-openapi.yml