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

# Ads

> Upload audio files and broadcast them to your locations using External IDs.

The Ads integration lets you upload MP3 audio files — announcements, promotions, jingles — and send them to specific store locations or broadcast them across your entire network.

***

## Core Concepts

### External ID Mapping

Your **External ID** is your internal identifier for a location or store. Musique maps these to internal user IDs, so you always work with your own identifiers — no need to track Musique-internal IDs.

```
External ID    →    Musique User    →    Device
store_001      →    mp1             →    Raspberry Pi at Location A
store_042      →    mp2             →    Raspberry Pi at Location B
```

### Targeted Send vs Broadcast

<Tabs>
  <Tab title="Targeted Send">
    Send audio to specific locations by listing their External IDs:

    ```json theme={null}
    POST /api/v1/integration/audio/{id}/send
    {
      "externalIds": ["store_001", "store_042"]
    }
    ```

    Use this for regional campaigns or testing before a wider rollout.
  </Tab>

  <Tab title="Broadcast">
    Send audio to **all** locations associated with your token by passing an empty array:

    ```json theme={null}
    POST /api/v1/integration/audio/{id}/send
    {
      "externalIds": []
    }
    ```

    Use this for company-wide announcements.
  </Tab>
</Tabs>

***

## Quick Start

Upload a file and send it to locations in two requests:

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

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

<Note>
  Always test with a single `externalId` before broadcasting to all locations.
</Note>

***

## Endpoints

<CardGroup cols={2}>
  <Card title="List Audio" icon="list" href="/api-reference/audio/integration-audio-controller-list-audios">
    Retrieve all audio files in your library.
  </Card>

  <Card title="Upload Audio" icon="upload" href="/api-reference/audio/integration-audio-controller-upload-audio">
    Upload a new MP3 file to your library.
  </Card>

  <Card title="Get Audio" icon="file-audio" href="/api-reference/audio/integration-audio-controller-get-audio-by-id">
    Retrieve a specific audio file by ID.
  </Card>

  <Card title="Send Audio" icon="paper-plane" href="/api-reference/audio/integration-audio-controller-send-audio-broadcast">
    Broadcast audio to devices by External ID.
  </Card>
</CardGroup>