> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beatpass.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Explore BeatPass API endpoints with the interactive OpenAPI explorer.

## API Reference

This section documents all public-facing BeatPass API endpoints. Browse the OpenAPI specification or explore specific API domains:

### API Documentation

<CardGroup cols={3}>
  <Card title="Dashboard API" icon="chart-mixed" href="/developers/api-reference/dashboard">
    Producer dashboard metrics, track performance, and upload insights.
  </Card>

  <Card title="Insights API" icon="chart-line" href="/developers/api-reference/insights">
    Analytics and insights for tracks, albums, and artists.
  </Card>

  <Card title="Commerce & Licensing" icon="cart-shopping" href="/developers/api-reference/commerce">
    Purchases, licenses, safe finance references, and exclusive presets.
  </Card>

  <Card title="Messaging API" icon="messages" href="/developers/api-reference/messaging">
    Direct messages, conversations, and real-time features.
  </Card>

  <Card title="Beat Requests API" icon="wave-square" href="/developers/api-reference/beat-requests">
    Custom beat request marketplace and fulfillment.
  </Card>

  <Card title="Social API" icon="users" href="/developers/api-reference/social">
    Following, reposts, user library, and social graph.
  </Card>

  <Card title="Content API" icon="record-vinyl" href="/developers/api-reference/content">
    Tracks, albums, artists, lyrics, fingerprinting, Audio Recon, and Backstage producer requests.
  </Card>

  <Card title="Search & Discovery" icon="magnifying-glass" href="/developers/api-reference/search">
    Search, genres, tags, radio, and leaderboards.
  </Card>

  <Card title="Producer Intelligence" icon="trophy" href="/developers/api-reference/producer-intelligence">
    XP, achievements, social analytics, and charts.
  </Card>
</CardGroup>

### OpenAPI Explorer

The API reference uses the BeatPass OpenAPI specification to provide interactive documentation for all endpoints. Browse by category in the **Endpoint Explorer** section of the navigation.

<Info>
  **Base URL:** `https://open.beatpass.ca/api/v1`
</Info>

***

## Using the API Explorer

<Steps>
  <Step title="Select an Endpoint">
    Expand the **Endpoint Explorer** in the sidebar and choose a category:

    * **Search** — Full-text search across content
    * **Tracks** — Track listing, details, and management
    * **Artists** — Artist profiles and followers
    * **Albums** — Album management
    * **Playlists** — Playlist CRUD and collaboration
    * **License Certificates** — License generation and verification
    * And more...
  </Step>

  <Step title="Review Parameters">
    Each endpoint shows required and optional parameters, request body schemas, and example values.
  </Step>

  <Step title="Try It Out">
    Use the **Try It** feature to test endpoints directly. Enter your Bearer token in the **Authorization** field for authenticated endpoints.
  </Step>

  <Step title="Check Responses">
    Response schemas show the expected data structure. Error responses (401, 403, 404, 422) are documented for each endpoint.
  </Step>
</Steps>

***

## Authentication & Access Tiers

The data you receive depends on your authentication level:

<AccordionGroup>
  <Accordion title="Public (No Token)" icon="globe" defaultOpen>
    <Badge color="gray" size="lg">Minimal Data</Badge>

    Unauthenticated requests return **minimal data only** — just enough to identify resources:

    * Tracks: `id`, `name`, `image`, `created_at`, `duration_text`, `model_type`
    * Artists/Genres: `id`, `name`, `model_type`

    No pricing, plays, licensing, or internal fields are included.
  </Accordion>

  <Accordion title="Bearer Token (Approved Developers)" icon="key">
    <Badge color="blue" size="lg">Rich Data</Badge>

    Authenticated requests with a valid **Bearer token** return rich API data including pricing, play counts, BPM, key/scale, licensing type, and more.

    <Warning>
      API access is **invite-only**. Developer tokens are granted on a case-by-case basis. To request access, contact [**contact@beatpass.ca**](mailto:contact@beatpass.ca). See [Authentication](/developers/auth) for details.
    </Warning>
  </Accordion>
</AccordionGroup>

### Using the Playground

To get **rich responses** from the API playground, you must have an approved developer token:

1. Once approved, go to **Account Settings → Developers** on [open.beatpass.ca](https://open.beatpass.ca) to generate a token
2. Click the **Authorization** button in the playground
3. Enter your token (without the `Bearer` prefix — Mintlify adds it automatically)
4. Send your request

<Info>
  Without a token, public endpoints return **minimal data only** (id, name, image, model\_type). To get rich responses with pricing, plays, BPM, and licensing data, enter your approved developer token.
</Info>

***

## Quick Examples

### Public Request (Minimal Data)

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# Returns minimal track data (id, name, image, artists only)
curl "https://open.beatpass.ca/api/v1/tracks" \
  -H "Accept: application/json"
```

### Authenticated Request (Rich Data)

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# Returns full track data (pricing, plays, BPM, licensing, etc.)
curl "https://open.beatpass.ca/api/v1/tracks" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
```

### JavaScript Example

```javascript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
const response = await fetch('https://open.beatpass.ca/api/v1/tracks/3629', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
});
const data = await response.json();
console.log(data.track.name); // "ZOOM"
```

***

## Endpoint Categories

<Tabs>
  <Tab title="Public">
    These endpoints work without authentication (enhanced data when logged in):

    <CardGroup cols={2}>
      <Card title="Search" icon="magnifying-glass">
        <Badge color="green">Optional Auth</Badge>
        Full-text search across all content types.
      </Card>

      <Card title="Tracks" icon="record-vinyl">
        <Badge color="green">Read: Optional</Badge>
        Track listing and details.
      </Card>

      <Card title="Artists" icon="user-music">
        <Badge color="green">Read: Optional</Badge>
        Artist profiles and followers.
      </Card>

      <Card title="Albums" icon="layer-group">
        <Badge color="green">Read: Optional</Badge>
        Album listing and metadata.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Mixed Auth">
    Some operations require authentication:

    <CardGroup cols={2}>
      <Card title="Playlists" icon="list-music">
        <Badge color="orange">Mixed</Badge>
        Read public, write requires auth.
      </Card>

      <Card title="Users" icon="user">
        <Badge color="orange">Mixed</Badge>
        Public profiles, private data requires auth.
      </Card>
    </CardGroup>
  </Tab>

  <Tab title="Auth Required">
    Full authentication required:

    <CardGroup cols={2}>
      <Card title="Insights" icon="chart-line" color="#8b5cf6">
        <Badge color="red">Required</Badge>
        Analytics and insights for content.
      </Card>

      <Card title="License Certificates" icon="file-certificate">
        <Badge color="red">Required</Badge>
        Generation and verification.
      </Card>

      <Card title="Messaging" icon="messages">
        <Badge color="red">Required</Badge>
        Direct message conversations.
      </Card>

      <Card title="Beat Requests" icon="wave-square">
        <Badge color="red">Required</Badge>
        Beat request marketplace.
      </Card>

      <Card title="Audio Recon" icon="radar">
        <Badge color="red">Required</Badge>
        Detected audio similarities on streaming platforms.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>

<Tip>
  The [Insights API](/developers/api-reference/insights) provides focused, domain-specific analytics endpoints with standardized error handling and export capabilities.
</Tip>

***

## Related Resources

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/developers/auth">
    Authentication methods and token generation.
  </Card>

  <Card title="Error Catalog" icon="triangle-exclamation" href="/developers/error-catalog">
    Error codes and resolutions.
  </Card>
</CardGroup>