Audius Api Sdk

Get API Credentials

1. Create an Audius account if needed.
2. Go to audius.co/settings → "Manage Your Apps," or use api.audius.co/plans.
3. Create a developer app and obtain API Key and API Secret.
4. Treat API Secret like a password—never expose it on the frontend.

REST API

Base URL: https://api.audius.co/v1

Send x-api-key header with your API Key on every request. For writes (upload, favorite, repost), use OAuth or include API Secret per endpoint requirements.

Example (fetch track):

curl -H "x-api-key: YOUR_API_KEY" "https://api.audius.co/v1/tracks/D7KyD"

Example (search tracks):

curl -H "x-api-key: YOUR_API_KEY" "https://api.audius.co/v1/tracks/search?query=audius"

Full reference: docs.audius.co/api

Swagger / OpenAPI

The API is fully described by OpenAPI 3.0 specs. Ingest these for code generation, API exploration, or AI-assisted development.

For AI agents: Fetch and include the swagger spec in your context to understand endpoints, request/response shapes, and auth. Example:

curl -o audius-swagger.yaml "https://api.audius.co/v1/swagger.yaml"

Or reference the URL directly when your tool supports remote OpenAPI ingestion. The spec documents users, tracks, playlists, comments, resolve, tips, challenges, developer-apps, explore, events, and more.

Install SDK

Node.js:

npm install @audius/sdk

HTML (CDN):

<script src="https://cdn.jsdelivr.net/npm/@audius/sdk@latest/dist/sdk.min.js"></script>

SDK is assigned to window.audiusSdk when using the CDN.

Initialize SDK

import { sdk } from '@audius/sdk'

const audiusSdk = sdk({
  apiKey: 'Your API Key goes here',
  apiSecret: 'Your API Secret goes here' // Required for writes; omit for frontend
})

• Read-only: Use apiKey only. Safe for frontend.
• Writes (upload, favorite, repost): Add apiSecret. Use only on the server—never in browser.

First API Calls

// Fetch a track
const track = await audiusSdk.tracks.getTrack({ trackId: 'D7KyD' })

// Get user by handle
const user = await audiusSdk.users.getUserByHandle({ handle: 'audius' })
const userId = user.data?.id

// Favorite a track (requires apiSecret)
await audiusSdk.tracks.favoriteTrack({ trackId: 'D7KyD', userId })

create-audius-app

Scaffold a new Audius app. Requires Node >= 18.

Interactive:

npx create-audius-app

Non-interactive:

npx create-audius-app my-first-audius-app

Output layout:

my-app
├── README.md
├── index.html
├── package.json
├── public
├── src
│   ├── App.tsx
│   ├── main.tsx
│   └── ...
├── tsconfig.json
└── vite.config.ts

Options: npx create-audius-app --help

API Endpoints (Key Groups)

Full reference: docs.audius.co/api. For machine-readable details, ingest swagger.yaml.

OAuth / Log in with Audius

OAuth flow so your users sign in with Audius and authorize your app to act on their behalf. Required for user-specific actions (favorites, uploads, etc.).

• SDK OAuth helpers run in the browser only.
• For server-side flows, see the manual implementation guide.

Log in with Audius Guide

Image Loading and Mirrors

Images (artwork, profile pictures) often fail to load if you do not retry from mirrors. API responses include image URLs and a mirrors array of alternate hosts.

Artwork structure example:

{
  "artwork": {
    "150x150": "https://audius-content-7.example.com/content/.../150x150.jpg",
    "480x480": "https://audius-content-7.example.com/content/.../480x480.jpg",
    "1000x1000": "https://audius-content-7.example.com/content/.../1000x1000.jpg",
    "mirrors": [
      "https://audius-creator-6.theblueprint.xyz",
      "https://cn0.mainnet.audiusindex.org",
      "https://creatornode2.audius.co"
    ]
  }
}

Critical for agents:

1. Never strip mirrors. Do not normalize artwork to a single URL string—preserve mirrors so retries can swap hosts.
2. Use mirror retry on load failure. When an image fails to load, replace the URL host with each mirror in order and retry until one succeeds or all fail.
3. Apply everywhere. Use a shared image component with mirror retry for all Audius images (tracks, playlists, profiles). Raw <img src={url}> has no retry.
4. Size-aware selection. Pick the variant (150x150, 480x480, 1000x1000) closest to the rendered size.

Full guide: Image Loading & Mirrors

Web Examples (Vite + React)

Runnable examples live in the apps monorepo under packages/web/examples/. Use them for SDK setup, trending, artwork with mirrors, and playback.

Key files (web trending): src/sdk.ts (getSDK), src/hooks/useTrendingTracks.ts, src/components/TrackArtworkImage.tsx (mirror retry on image error), src/utils/artwork.ts (getArtworkUrl, getNextMirrorUrl), src/App.tsx (play/stop with single Audio ref).

Key files (web update-profile): src/sdk.ts, src/config.ts, src/oauth/buildOAuthUrl.ts, src/App.tsx (OAuth redirect, form, update POST), server/server.js (developer app bearer, updateUser).

Key files (web upload): src/sdk.ts, src/config.ts, src/oauth/buildOAuthUrl.ts, src/App.tsx (OAuth popup, file picker, uploadTrackFiles, create-track POST), server/server.js (createTrack).

Key files (web gated-upload): Same as upload; server adds /stream/:trackId (geo-gate via ip-api.com) and /my-region.

Keywords: SDK setup, Vite, React, trending tracks, getTrendingTracks, getTrackStreamUrl, track artwork, mirrors, React Query, OAuth, update profile, verifyIDToken, updateUser, upload track, uploadTrackFiles, createTrack, geo-gated streaming, web example.

Mobile Examples (Expo + React Native)

Runnable examples in apps under packages/mobile/examples/. Use them for OAuth, server-held bearer, like/repost, and update-profile.

Keywords (mobile): SDK setup, Expo, React Native, OAuth, bearer token, getSDK, polyfills, trending, like, repost, favoriteTrack, repostTrack, updateUser, developer app bearer, server-side writes.

Other Examples & References

• create-audius-app examples — React, React + Hono templates
• Swagger spec — Ingest for API discovery, codegen, or AI context
• SDK Tracks
• SDK Users
• SDK Playlists
• Postman collection

Links

Recommendations only. Build something new.