> ## 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.

# Quickstart

> Getting started guide for approved developers working with the BeatPass API.

## Overview

This guide helps approved developers get started with the BeatPass API.

<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>

***

## Authentication

All API requests use **Bearer token authentication**:

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/tracks
Authorization: Bearer {your-token}
Accept: application/json
```

| Detail               | Value                                 |
| -------------------- | ------------------------------------- |
| **Access**           | Invite-only, granted by BeatPass team |
| **Token expiration** | 90 days from creation                 |
| **Data access**      | Token required for rich API responses |

<Info>
  **Unauthenticated requests return minimal data** (id, name, model\_type only). A valid Bearer token is required for rich responses with pricing, plays, BPM, and licensing info.
</Info>

***

## Environment

### No Public Sandbox

<Warning>
  **No Public Sandbox** — BeatPass does not provide a public sandbox or test environment. All API calls hit production systems.
</Warning>

This means:

| Action                   | Impact                          |
| ------------------------ | ------------------------------- |
| POST/PUT/DELETE requests | **Real data is modified**       |
| Purchases                | **Real charges occur**          |
| Uploads                  | **Real content is published**   |
| Messages                 | **Real users receive messages** |

### Development Best Practices

| Practice                            | Why                                 |
| ----------------------------------- | ----------------------------------- |
| Use personal test accounts          | Avoid affecting real users          |
| Test with minimal data              | Don't create spam content           |
| Clean up test data                  | Delete test uploads promptly        |
| Never test payments with real cards | Use Stripe test mode when available |

***

## Using Placeholder IDs

When developing or documenting:

### Recommended Placeholders

| Entity    | Placeholder Format | Example                |
| --------- | ------------------ | ---------------------- |
| Track ID  | `{track_id}`       | `/tracks/{track_id}`   |
| User ID   | `{user_id}`        | `/users/{user_id}`     |
| Artist ID | `{artist_id}`      | `/artists/{artist_id}` |
| Album ID  | `{album_id}`       | `/albums/{album_id}`   |

### In Code Examples

```javascript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
// Good - uses placeholder
const trackId = process.env.TEST_TRACK_ID || '{track_id}';

// Bad - hardcodes production ID
const trackId = 12345;
```

### In Documentation

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/tracks/{track_id}
```

Not:

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/tracks/12345
```

***

## Restricted Access

<Warning>
  **Undocumented endpoints are off-limits.** Unauthorized access attempts are logged, monitored, and may result in immediate token revocation and account termination.
</Warning>

If you encounter a 403 Forbidden response, the endpoint requires permissions your account does not have. Contact support if you believe this is an error.

***

## Safe API Usage

### Do

* Use documented endpoints only
* Respect rate limits
* Handle errors gracefully
* Clean up test data
* Log responsibly (no sensitive data)

### Don't

* Scrape or crawl the platform
* Hammer endpoints with excessive requests
* Store user credentials
* Bypass authentication
* Share authentication credentials

***

## Error Handling

### Standard Error Format

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "message": "Human-readable error",
  "errors": {
    "field": ["Validation error message"]
  }
}
```

### HTTP Status Codes

| Code | Meaning          | Action                 |
| ---- | ---------------- | ---------------------- |
| 200  | Success          | Process response       |
| 201  | Created          | Resource created       |
| 400  | Bad Request      | Fix request format     |
| 401  | Unauthorized     | Re-authenticate        |
| 403  | Forbidden        | Check permissions      |
| 404  | Not Found        | Resource doesn't exist |
| 422  | Validation Error | Fix input data         |
| 429  | Rate Limited     | Back off and retry     |
| 500  | Server Error     | Report to support      |

See [Error Catalog](/developers/error-catalog) for feature-specific errors.

***

## Getting Help

| Topic                 | Contact                                           |
| --------------------- | ------------------------------------------------- |
| API questions         | [contact@beatpass.ca](mailto:contact@beatpass.ca) |
| Security concerns     | [contact@beatpass.ca](mailto:contact@beatpass.ca) |
| Partnership inquiries | [contact@beatpass.ca](mailto:contact@beatpass.ca) |

### Documentation

| Topic          | Location                                                                 |
| -------------- | ------------------------------------------------------------------------ |
| API Overview   | [/developers/overview](/developers/overview)                             |
| API Reference  | [/developers/api-reference/overview](/developers/api-reference/overview) |
| Authentication | [/developers/auth](/developers/auth)                                     |
| Rate Limits    | [/developers/rate-limits](/developers/rate-limits)                       |
| Error Catalog  | [/developers/error-catalog](/developers/error-catalog)                   |

***

## Getting Started Checklist

<Steps>
  <Step title="Request API Access">
    Contact [**contact@beatpass.ca**](mailto:contact@beatpass.ca) with your use case and organization details.
  </Step>

  <Step title="Generate Token">
    Once approved, go to **Account Settings → Developers** to create your token.
  </Step>

  <Step title="Review Documentation">
    * Read the [API Overview](/developers/overview)
    * Understand [Authentication](/developers/auth)
    * Note [Rate Limits](/developers/rate-limits)
  </Step>

  <Step title="Start Building">
    * Begin with read-only endpoints (tracks, artists, search)
    * Use placeholder IDs in development
    * Monitor rate limit headers
    * Handle errors gracefully
  </Step>
</Steps>

***

## Related Resources

<CardGroup cols={2}>
  <Card title="API Overview" icon="book" href="/developers/overview">
    Full API introduction.
  </Card>

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