Getting Started with the Audius SDK

Overview

The Audius JavaScript (TypeScript) SDK allows you to easily interact with the Open Audio Protocol. Use the SDK to:

🔍 Search and display users, tracks, and playlists
🎵 Stream and upload tracks
❤️ Favorite, repost, and curate playlists
✍️ Allow your users to log in with their Audius account and act on their behalf

...and much more!

API Plans

Audius offers two API plans:

Plan	Rate Limit	Monthly Requests
Free	10 requests/second	500,000 requests/month
Unlimited	Unlimited	Unlimited

The Free plan is always free with no restrictions. For higher limits and support, contact api@audius.co about the Unlimited plan.

Get Your API Key

Visit the Audius API Plans page and click "Create API Key" to generate your credentials.
You will receive an API Key and a Bearer Token.

API Key — used in all contexts (frontend and backend). Safe to include in client-side code.
Bearer Token — backend only. Grants your app the ability to act on behalf of users who have authorized it. Never expose this in browser or mobile code.

Install the SDK

Node.js

If your project is in a Node.js environment, run this in your terminal:

npm install @audius/sdk

@audius/sdk on NPM

HTML + JS

Otherwise, include the SDK script tag in your web page. The Audius SDK will then be assigned to window.audiusSdk.

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

Initialize the SDK

How you initialize the SDK depends on whether you are running in a backend (Node.js) or frontend (browser/mobile) context.

Node.js (backend) example

Include your API key and bearer token. The bearer token enables your app to perform actions on behalf of authorized users.

In Node.js environment

import { sdk } from '@audius/sdk'
 
const audiusSdk = sdk({
  apiKey: 'Your API Key goes here',
  bearerToken: 'Your Bearer Token goes here',
})

HTML + JS (frontend) example

In a browser or mobile context, initialize with your API key only — no bearer token. User authentication is handled via the OAuth flow described below.

In web page

const audiusSdk = window.audiusSdk({
  apiKey: 'Your API Key goes here',
})

Make your first API call using the SDK

Once you have the initialized SDK instance, it's smooth sailing to making your first API calls.

// Fetch your first track!
const track = await audiusSdk.tracks.getTrack({ trackId: 'D7KyD' })
console.log(track, 'Track fetched!')
 
// Favorite a track
const userId = (
  await audiusSdk.users.getUserByHandle({
    handle: 'Your Audius handle goes here',
  })
).data?.id
await audiusSdk.tracks.favoriteTrack({
  trackId: 'D7KyD',
  userId,
})

Full Node.js example

app.js

import { sdk } from '@audius/sdk'
 
const audiusSdk = sdk({
  apiKey: 'Your API Key goes here',
  bearerToken: 'Your Bearer Token goes here',
})
 
const track = await audiusSdk.tracks.getTrack({ trackId: 'D7KyD' })
console.log(track, 'Track fetched!')
 
const userId = (
  await audiusSdk.users.getUserByHandle({
    handle: 'Your Audius handle goes here',
  })
).data?.id
 
await audiusSdk.tracks.favoriteTrack({
  trackId: 'D7KyD',
  userId,
})
console.log('Track favorited!')

Full HTML + JS example

index.html

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.jsdelivr.net/npm/@audius/sdk@latest/dist/sdk.min.js"></script>
    <script>
      const fn = async () => {
        const audiusSdk = window.audiusSdk({
          apiKey: 'Your API Key goes here',
        })
        const track = await audiusSdk.tracks.getTrack({ trackId: 'D7KyD' })
        console.log(track, 'Track fetched!')
      }
 
      fn()
    </script>
  </head>
  <body>
    <h1>Example content</h1>
  </body>
</html>

Log In with Audius (OAuth)

For frontend apps, use the built-in OAuth 2.0 PKCE flow to authenticate users. This lets your users log in with their Audius account and authorize your app to act on their behalf — without exposing your app's bearer token in client-side code.

In web page

const audiusSdk = window.audiusSdk({
  apiKey: 'Your API Key goes here',
  redirectUri: 'https://your-app.com/oauth/callback'
})
 
// Redirect the user to Audius to log in
audiusSdk.oauth.login()
 
// On your callback page, handle the redirect:
await audiusSdk.oauth.handleRedirectCallback()

After the user logs in, the SDK stores their access token automatically and includes it in subsequent API calls. See the Log In with Audius guide for the full flow.

What's next?

Log in with Audius — add OAuth authentication to your frontend app
Explore the API docs to see what else you can do with the Audius SDK

Direct API Access

You can also access the Audius API directly without the SDK. The examples below use a bearer token and are intended for backend/server-side use only — do not use your bearer token in browser or mobile code.

REST API:

curl -X GET "https://api.audius.co/v1/tracks/trending" \
  -H "Authorization: Bearer <YOUR-API-BEARER-TOKEN>"

gRPC:

grpcurl -H "authorization: Bearer <YOUR-API-BEARER-TOKEN>" \
  grpc.audius.co:443 list

For more details, visit the API documentation or the Swagger definition.