OpenAPI Specification
openapi: 3.0.1
info:
title: Audius challenges prizes 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: prizes
description: Prize claiming related operations
paths:
/prizes:
get:
tags:
- prizes
operationId: Get Prizes
description: Gets a list of active prizes available for claiming. Excludes sensitive information like download URLs.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/prizes_response'
'500':
description: Server error
content: {}
/prizes/claim:
post:
tags:
- prizes
operationId: Claim Prize
description: Claims a prize by verifying a Solana transaction. User must send exactly 2 YAK to the prize receiver address. Returns the prize won and any redeem codes/URLs.
requestBody:
x-codegen-request-body-name: claim
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/prize_claim_request_body'
responses:
'200':
description: Success - Prize claimed
content:
application/json:
schema:
$ref: '#/components/schemas/prize_claim_response'
'400':
description: Bad request - Transaction not found, invalid, or signature already used
content: {}
'500':
description: Server error
content: {}
/wallet/{wallet}/prizes:
get:
tags:
- prizes
operationId: Get Wallet Prizes
description: Gets all claimed prizes for a wallet. Public endpoint - no authentication required. Excludes sensitive action_data for security.
parameters:
- name: wallet
in: path
description: The wallet address to get prizes for
required: true
schema:
type: string
example: HLnpSz9h2S4hiLQ43rnSD9XkcUThA7B8hQMKmDaiTLcC
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/claimed_prizes_response'
'400':
description: Bad request - Missing wallet parameter
content: {}
'500':
description: Server error
content: {}
components:
schemas:
claimed_prize:
type: object
required:
- id
- wallet
- signature
- mint
- amount
- prize_id
- prize_name
- created_at
properties:
id:
type: integer
description: The unique identifier of the claimed prize record
example: 1
wallet:
type: string
description: The wallet address that claimed the prize
example: HLnpSz9h2S4hiLQ43rnSD9XkcUThA7B8hQMKmDaiTLcC
signature:
type: string
description: The transaction signature used to claim the prize
example: 5j7s1QjmRKFuDbCWMRVRNibSV2VAAEcNKP6HWU7GwPdXkBZvhz8n4vQl7bBq8tN4Rz9x1Kj3mP5wQ8rT2Y6zA
mint:
type: string
description: The coin mint address used for the claim
example: ZDaUDL4XFdEct7UgeztrFQAptsvh4ZdhyZDZ1RpxYAK
amount:
type: integer
description: The amount paid to claim the prize (in smallest unit, e.g., lamports)
example: 2000000000
prize_id:
type: string
description: The unique identifier of the prize won
example: prize_1_yak_airdrop
prize_name:
type: string
description: The name of the prize won
example: 1 YAK Airdrop
prize_type:
type: string
description: The type of prize (e.g., "coin_airdrop", "download")
example: coin_airdrop
created_at:
type: string
format: date-time
description: When the prize was claimed
example: '2024-01-15T10:30:00Z'
prize_claim_request_body:
type: object
required:
- signature
- wallet
properties:
signature:
type: string
description: The Solana transaction signature for the 2 YAK payment
example: 5j7s1QjmRKFuDbCWMRVRNibSV2VAAEcNKP6HWU7GwPdXkBZvhz8n4vQl7bBq8tN4Rz9x1Kj3mP5wQ8rT2Y6zA
wallet:
type: string
description: The wallet address that sent the transaction
example: HLnpSz9h2S4hiLQ43rnSD9XkcUThA7B8hQMKmDaiTLcC
claimed_prizes_response:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/claimed_prize'
description: List of claimed prizes for the wallet (action_data excluded for security)
prizes_response:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/prize_public'
description: List of active prizes available for claiming
prize_public:
type: object
required:
- prize_id
- name
- weight
properties:
prize_id:
type: string
description: The unique identifier of the prize
example: prize_1_yak_airdrop
name:
type: string
description: The name of the prize
example: 1 YAK Airdrop
description:
type: string
description: Description of the prize
example: Win 1 YAK coin airdrop
weight:
type: integer
description: Weight for random selection (higher = more likely)
example: 1
metadata:
type: object
description: Sanitized metadata (excludes sensitive URLs)
additionalProperties: true
example:
type: coin_airdrop
amount: 1000000000
prize_claim_response:
type: object
required:
- prize_id
- prize_name
- wallet
properties:
prize_id:
type: string
description: The unique identifier of the prize won
example: prize_1_yak_airdrop
prize_name:
type: string
description: The name of the prize won
example: 1 YAK Airdrop
wallet:
type: string
description: The wallet address that claimed the prize
example: HLnpSz9h2S4hiLQ43rnSD9XkcUThA7B8hQMKmDaiTLcC
prize_type:
type: string
description: The type of prize (e.g., "coin_airdrop", "download")
example: coin_airdrop
action_data:
type: object
description: Prize-specific action data (e.g., redeem code/URL for coin airdrops, download URL for downloads)
additionalProperties: true
example:
code: aB3d5F
url: /coins/YAK/redeem/aB3d5F
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'