OpenAPI Specification
openapi: 3.0.1
info:
title: Audius challenges rewards 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: rewards
description: Rewards related operations
paths:
/rewards/claim:
post:
tags:
- rewards
description: Claims all the filtered undisbursed rewards for a user
operationId: Claim Rewards
requestBody:
x-codegen-request-body-name: reward
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/claim_rewards_request_body'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/claim_rewards_response'
'400':
description: Bad request - No rewards to claim or invalid parameters
content: {}
'500':
description: Server error
content: {}
/rewards/code:
post:
tags:
- rewards
description: Creates a new reward code with Solana signature verification
operationId: Create Reward Code
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_reward_code_request'
responses:
'201':
description: Created - Reward code successfully created
content:
application/json:
schema:
$ref: '#/components/schemas/create_reward_code_response'
'400':
description: Bad request - Invalid signature format or missing required fields
content: {}
'403':
description: Forbidden - Signature verification failed
content: {}
'500':
description: Server error
content: {}
components:
schemas:
create_reward_code_response:
type: object
required:
- code
- mint
- reward_address
- amount
properties:
code:
type: string
description: The generated 6-character alphanumeric reward code
example: aB3d5F
mint:
type: string
description: The coin mint address
example: 9LzCMqDgTKYz9Drzqnpgee3SGa89up3a247ypMj2xrqM
reward_address:
type: string
description: The reward address (authorized public key)
example: 9XeZbswbSSUU4AHVArQbTQjAEjAPhVweGU5cogBVkvh4
amount:
type: integer
description: The reward amount
example: 100
claim_rewards_response:
type: object
required:
- data
properties:
data:
type: array
items:
type: object
required:
- challengeId
- specifier
properties:
challengeId:
type: string
description: The challenge ID
example: u
specifier:
type: string
description: The challenge specifier
example: 7eP5n
amount:
type: string
description: The reward amount
example: '1000000000'
signatures:
type: array
items:
type: string
description: Transaction signatures
example:
- 5j7s1QjmRKFuDbCWMRVRNibSV2VAAEcNKP6HWU7GwPdXkBZvhz8n4vQl7bBq8tN4Rz9x1Kj3mP5wQ8rT2Y6zA
error:
type: string
description: Error message if claim failed
example: Insufficient balance
create_reward_code_request:
type: object
required:
- signature
- mint
- amount
properties:
signature:
type: string
description: Base64-encoded Solana Ed25519 signature of the string "code"
example: 3fG7xQh2L8vK9pN4mR5sT6uW7vX8yZ1aB2cD3eF4gH5iJ6kL7mN8oP9qR0sT1uV2wX3yZ4aB5cD6eF7gH8iJ9k=
mint:
type: string
description: The coin mint address
example: 9LzCMqDgTKYz9Drzqnpgee3SGa89up3a247ypMj2xrqM
amount:
type: integer
description: The reward amount (must be greater than 0)
minimum: 1
example: 100
claim_rewards_request_body:
type: object
required:
- userId
properties:
challengeId:
type: string
description: The challenge ID to filter rewards (optional)
example: u
specifier:
type: string
description: The specifier to filter rewards (optional)
example: 7eP5n
userId:
type: string
description: The user ID to claim rewards for
example: 7eP5n
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'