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

# API Reference

> Partner API for audio management, device control, and business automation

The Musique Partner API lets you programmatically upload audio, schedule broadcasts, and manage your audio library across all your locations — built for retailers, franchises, and multi-unit businesses.

**Base URL**

```
https://api.musique.app/api/v1/integration
```

***

## Authentication

All requests require an `X-API-Key` header. Each user within a company receives a unique token with three parts:

```
{companyPrefix}_{environmentPrefix}_{hashToken}
```

For example: `msk_prod_1234567890abcdef` — where `msk` is the company prefix, `prod` is the environment, and `1234567890abcdef` is the unique hash.

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

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

<Note>
  API tokens are issued by the Musique team. Contact [support@musique.app](mailto:support@musique.app) to get yours.
</Note>

***

## Explore the API

<CardGroup cols={2}>
  <Card title="Audio Endpoints" icon="waveform" href="/api-reference/audio/integration-audio-controller-list-audios">
    Upload, retrieve, send, and delete audio files across all your locations.
  </Card>

  <Card title="System Monitoring" icon="server" href="/api-reference/system/integration-health-controller-get-info">
    Check API health, version info, and current service status.
  </Card>
</CardGroup>

***

## Quick Start

Get up and running in two steps.

<Steps>
  <Step title="Upload an audio file">
    ```bash theme={null}
    curl -X POST https://api.musique.app/api/v1/integration/audio \
      -H "X-API-Key: msk_live_1234567890abcdef" \
      -F "file=@announcement.mp3"
    ```

    Response includes an `id` you'll use to send the file to devices.
  </Step>

  <Step title="Broadcast to devices">
    ```bash theme={null}
    curl -X POST https://api.musique.app/api/v1/integration/audio/{id}/send \
      -H "X-API-Key: msk_live_1234567890abcdef" \
      -H "Content-Type: application/json" \
      -d '{"externalIds": ["store_001", "store_042"]}'
    ```

    `externalIds` maps to your internal store or location identifiers.
  </Step>
</Steps>

***

## Endpoints

### Audio

| Method   | Path               | Description                |
| -------- | ------------------ | -------------------------- |
| `GET`    | `/audio`           | List all audio files       |
| `POST`   | `/audio`           | Upload a new MP3 file      |
| `GET`    | `/audio/{id}`      | Get a specific audio file  |
| `DELETE` | `/audio/{id}`      | Delete an audio file       |
| `POST`   | `/audio/{id}/send` | Broadcast audio to devices |

### System

| Method | Path      | Description                     |
| ------ | --------- | ------------------------------- |
| `GET`  | `/`       | API name, version, and docs URL |
| `GET`  | `/health` | Health check and service status |

***

## Response Format

All successful responses return JSON. Error responses 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 error codes and handling examples.

***

## Rate Limits

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

Standard limits are enforced 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. On limit exceeded, you'll receive `429 Too Many Requests` with a `Retry-After` header.

***

## SDKs

<Note>
  Official SDKs are coming soon. Use any HTTP client in the meantime.
</Note>

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

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

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

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

***

## Support

Questions or need a token? Reach us at [support@musique.app](mailto:support@musique.app) or read the [Partner API Integration Guide](/essentials/partner-api).