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

# Getting Started

> Integrate Musique into your systems to manage audio and automate broadcasts across all your locations.

The Musique Partner API gives you programmatic control over your audio environment — built for retailers, franchises, and multi-unit businesses. Authenticate once with an API key and access two integration surfaces:

<CardGroup cols={2}>
  <Card title="Ads" icon="tower-broadcast" href="/essentials/ads">
    Upload MP3 files and broadcast them to specific locations or your entire network using External IDs.
  </Card>

  <Card title="Playlists" icon="music" href="/essentials/playlists" badge="Soon">
    Fetch curated playlists with CDN-served audio URLs for direct playback in your application.
  </Card>
</CardGroup>

***

## Getting Started

### 1. Request Integration Access

Contact Musique support to request Partner API access. Provide:

* Your company name and use case
* Your External ID scheme (how you identify your locations internally)

You'll receive an API token directly from the Musique team.

<Warning>
  Store your API token securely. Never expose it in client-side code or public repositories. Use environment variables or a secret manager.
</Warning>

### 2. Verify Your Connection

Test your token with a health check:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.musique.app/api/v1/integration/health \
    -H "X-API-Key: msk_prod_1234567890abcdef"
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api.musique.app/api/v1/integration/health', {
    headers: { 'X-API-Key': 'msk_prod_1234567890abcdef' }
  });
  const data = await res.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
    'https://api.musique.app/api/v1/integration/health',
    headers={'X-API-Key': 'msk_prod_1234567890abcdef'}
  )
  print(res.json())
  ```
</CodeGroup>

### 3. Explore the Integration Surfaces

<CardGroup cols={2}>
  <Card title="Ads" icon="tower-broadcast" href="/essentials/ads">
    Upload and broadcast audio files to your locations.
  </Card>

  <Card title="Playlists" icon="music" href="/essentials/playlists" badge="Soon">
    Stream curated background music playlists.
  </Card>
</CardGroup>

***

## Authentication

All requests must include your API token in the `X-API-Key` header:

```
X-API-Key: msk_prod_1234567890abcdef
```

**Token format**

Tokens are structured as `{companyPrefix}_{environmentPrefix}_{hashToken}`. Each user within a company gets a unique token.

| Part                | Description                                  |
| ------------------- | -------------------------------------------- |
| `companyPrefix`     | Identifies the partner company (e.g. `msk`)  |
| `environmentPrefix` | `prod` for production, `dev` for development |
| `hashToken`         | Unique hash per user                         |

<AccordionGroup>
  <Accordion title="Token Security">
    * Tokens are hashed in the database — Musique never stores the plaintext value
    * Each token is scoped to your company and External IDs
    * Tokens do not expire by default
    * If a token is compromised, contact [support@musique.app](mailto:support@musique.app) immediately to revoke it
  </Accordion>
</AccordionGroup>

***

## System Endpoints

<CardGroup cols={2}>
  <Card title="API Info" icon="circle-info" href="/api-reference/system/integration-health-controller-get-info">
    Get API name, version, and documentation URL.
  </Card>

  <Card title="Health Check" icon="heart-pulse" href="/api-reference/system/integration-health-controller-get-health">
    Check API health and service status.
  </Card>

  <Card title="Validate Token" icon="shield-check" href="/api-reference/system/validate-token" badge="Soon">
    Confirm your API key is valid and retrieve company and user details.
  </Card>
</CardGroup>

***

## Rate Limits

<Warning>
  **Coming soon** — Rate limit documentation and per-key usage endpoints are under development. See the [Rate Limits](/api-reference/rate-limits) page for planned specs.
</Warning>

Standard limits per API key:

| Window     | Limit           |
| ---------- | --------------- |
| Per minute | 100 requests    |
| Per hour   | 1,000 requests  |
| Per day    | 10,000 requests |

Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header.

***

## Response Format

All responses return JSON. Errors follow a consistent structure:

```json theme={null}
{
  "error": {
    "code": "invalid_token",
    "message": "Invalid or expired API token",
    "type": "authentication_error"
  }
}
```

See the [Errors](/api-reference/errors) page for a full list of codes and handling examples.

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Error Handling" icon="triangle-exclamation">
    Handle all error types explicitly. See the [Errors guide](/api-reference/errors) for per-status examples.
  </Card>

  <Card title="Rate Limiting" icon="clock">
    Implement exponential backoff on `429` responses. Start at 1 second and double each retry.
  </Card>

  <Card title="Token Security" icon="shield">
    Store tokens in environment variables or a secret manager. Rotate immediately if exposed.
  </Card>

  <Card title="OpenAPI Spec" icon="rectangle-terminal">
    Interactive playground and full spec available in the [API Reference](/api-reference/introduction).
  </Card>
</CardGroup>

***

## Support

Questions or need a token? Contact [support@musique.app](mailto:support@musique.app). When reporting an issue, include your External ID, the timestamp, and the error message.

<CardGroup cols={2}>
  <Card title="API Reference" icon="rectangle-terminal" href="/api-reference/introduction">
    Full endpoint docs with interactive playground.
  </Card>

  <Card title="Quick Messages Guide" icon="bolt" href="/learn/quick-messages">
    Learn how to create and manage audio content in the Musique dashboard.
  </Card>
</CardGroup>