Audio - Musique App

Overview

Audio endpoints allow you to upload audio files, send them to specific locations, and manage your audio library. All audio must be uploaded before it can be played on Raspberry Pi devices.

Supported formats: MP3, WAV, OGG, AAC
Max file size: 10MB per file
Recommended: MP3 at 128kbps or higher for best quality

Create Audio

Upload a new audio file to your Musique library.

Endpoint

POST /api/audio

Headers

X-API-Key

string

required

Your API authentication token

Content-Type

string

required

Must be multipart/form-data

Request Body

file

required

Audio file to upload (MP3, WAV, OGG, AAC)

name

string

required

Display name for the audio file

description

string

Optional description or notes about the audio

Request Example

curl -X POST https://api.musique.app/api/audio \
  -H "X-API-Key: msk_live_1234567890abcdef" \
  -F "file=@/path/to/audio.mp3" \
  -F "name=Store Announcement" \
  -F "description=New product launch announcement" \
  -F "category=announcement"

Response

audioId

string

Unique identifier for the uploaded audio

name

string

Display name of the audio file

url

string

CDN URL for the audio file

duration

number

Audio duration in seconds

size

number

File size in bytes

format

string

Audio format (mp3, wav, ogg, aac)

createdAt

string

ISO 8601 timestamp of upload

{
  "audioId": "aud_9x8y7z6w5v4u3t",
  "name": "Store Announcement",
  "url": "https://cdn.musique.app/audio/aud_9x8y7z6w5v4u3t.mp3",
  "duration": 45.2,
  "size": 1024000,
  "format": "mp3",
  "createdAt": "2024-01-15T10:30:00Z"
}

Send Audio

Send an audio file to one or more Raspberry Pi devices. Supports both single location sends and broadcasts to multiple locations.

Endpoint

POST /api/{audioId}/send

Headers

X-API-Key

string

required

Your API authentication token

Path Parameters

audioId

string

required

ID of the audio file to send

Request Body

externalIds

array

required

Array of external IDs for target locations. Single ID for specific location, multiple IDs for broadcast.

scheduleAt

string

ISO 8601 timestamp for scheduled playback. Omit for immediate playback.

priority

string

default:"normal"

Playback priority: low, normal, high, urgent. High/urgent interrupt current playback.

repeat

number

default:"1"

Number of times to play the audio (1-10)

volume

number

default:"100"

Playback volume percentage (0-100)

Request Examples

curl -X POST https://api.musique.app/api/aud_9x8y7z6w5v4u3t/send \
  -H "X-API-Key: msk_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "externalIds": ["store_001"],
    "priority": "high",
    "volume": 80
  }'

Response

sendId

string

Unique identifier for this send operation

audioId

string

ID of the audio file sent

destinations

array

Array of destination objects with external IDs and user IDs

scheduled

boolean

Whether the audio is scheduled for future playback

scheduleAt

string | null

Scheduled playback time or null for immediate

status

string

Send status: queued, scheduled, sent, failed

{
  "sendId": "snd_abc123def456",
  "audioId": "aud_9x8y7z6w5v4u3t",
  "destinations": [
    {
      "externalId": "store_001",
      "userId": 4348,
      "status": "queued"
    }
  ],
  "scheduled": false,
  "scheduleAt": null,
  "status": "sent"
}

Single vs Broadcast:

Single: One external ID in array → sends to specific location
Broadcast: Multiple external IDs → sends to all locations simultaneously

Broadcasts are atomic: either all destinations receive the audio or none do.

List Audio

Retrieve all audio files in your library with pagination and filtering options.

Endpoint

GET /api/audio

Headers

X-API-Key

string

required

Your API authentication token

Query Parameters

page

number

default:"1"

Page number for pagination

limit

number

default:"20"

Number of results per page (max 100)

Request Example

curl https://api.musique.app/api/audio?page=1&limit=10&category=announcement \
  -H "X-API-Key: msk_live_1234567890abcdef"

Response

data

array

Array of audio objects

pagination

object

Pagination metadata (page, limit, total, totalPages)

{
  "data": [
    {
      "audioId": "aud_9x8y7z6w5v4u3t",
      "name": "Store Announcement",
      "description": "New product launch",
      "category": "announcement",
      "url": "https://cdn.musique.app/audio/aud_9x8y7z6w5v4u3t.mp3",
      "duration": 45.2,
      "size": 1024000,
      "format": "mp3",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "audioId": "aud_1a2b3c4d5e6f7g",
      "name": "Emergency Alert",
      "description": "Fire drill announcement",
      "category": "announcement",
      "url": "https://cdn.musique.app/audio/aud_1a2b3c4d5e6f7g.mp3",
      "duration": 30.5,
      "size": 768000,
      "format": "mp3",
      "createdAt": "2024-01-14T09:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1
  }
}

Get Audio

Retrieve details for a specific audio file including usage statistics.

Endpoint

GET /api/audio/{audioId}

Headers

X-API-Key

string

required

Your API authentication token

Path Parameters

audioId

string

required

ID of the audio file

Request Example

curl https://api.musique.app/api/audio/aud_9x8y7z6w5v4u3t \
  -H "X-API-Key: msk_live_1234567890abcdef"

Response

audioId

string

Unique identifier for the audio

name

string

Display name of the audio file

url

string

CDN URL for the audio file

stats

object

Usage statistics (timesPlayed, lastPlayedAt, totalRecipients)

{
  "audioId": "aud_9x8y7z6w5v4u3t",
  "name": "Store Announcement",
  "description": "New product launch announcement",
  "category": "announcement",
  "url": "https://cdn.musique.app/audio/aud_9x8y7z6w5v4u3t.mp3",
  "duration": 45.2,
  "size": 1024000,
  "format": "mp3",
  "createdAt": "2024-01-15T10:30:00Z",
  "stats": {
    "timesPlayed": 47,
    "lastPlayedAt": "2024-01-20T14:22:00Z",
    "totalRecipients": 12
  }
}

Delete Audio

Permanently delete an audio file from your library.

Endpoint

DELETE /api/{audioId}

Headers

X-API-Key

string

required

Your API authentication token

Path Parameters

audioId

string

required

ID of the audio file to delete

Request Example

curl -X DELETE https://api.musique.app/api/aud_9x8y7z6w5v4u3t \
  -H "X-API-Key: msk_live_1234567890abcdef"

Response

deleted

boolean

Confirmation that the audio was deleted

audioId

string

ID of the deleted audio file

{
  "deleted": true,
  "audioId": "aud_9x8y7z6w5v4u3t"
}

Deleting audio is permanent and cannot be undone. Audio files with scheduled sends cannot be deleted until those sends are completed or cancelled.

Common Workflows

Send Immediate Announcement

Scenario: Send an urgent announcement to a specific store right now.Steps:

Upload audio: POST /api/audio with your announcement file
Send immediately: POST /api/{audioId}/send with priority: "urgent" and externalIds: ["store_001"]
Monitor: Check /api/integration/logs to confirm delivery

Schedule Daily Promotion

Scenario: Play a promotional message at all stores tomorrow at 3 PM.Steps:

Upload audio: POST /api/audio with promotional file
Schedule broadcast: POST /api/{audioId}/send with scheduleAt: "2024-01-16T15:00:00Z" and externalIds: ["store_001", "store_002", "store_003"]
Verify: GET /api/audio/{audioId} to check schedule status

Manage Audio Library

Scenario: Clean up old promotional audio files.Steps:

List all audio: GET /api/audio?category=promotion
Get details: GET /api/audio/{audioId} to check usage stats
Delete unused: DELETE /api/{audioId} for files not played recently

Test Audio Before Broadcast

Scenario: Test audio at one location before broadcasting to all.Steps:

Upload: POST /api/audio with test file
Send to test location: POST /api/{audioId}/send with externalIds: ["test_store"]
If successful, broadcast: POST /api/{audioId}/send with all store IDs

Documentation

Quickstart

Learn

API Reference

​Overview

​Create Audio

​Endpoint

​Headers

​Request Body

​Request Example

​Response

​Send Audio

​Endpoint

​Headers

​Path Parameters

​Request Body

​Request Examples

​Response

​List Audio

​Endpoint

​Headers

​Query Parameters

​Request Example

​Response

​Get Audio

​Endpoint

​Headers

​Path Parameters

​Request Example

​Response

​Delete Audio

​Endpoint

​Headers

​Path Parameters

​Request Example

​Response

​Common Workflows

​Next Steps

Authentication

System Endpoints

Overview

Create Audio

Endpoint

Headers

Request Body

Request Example

Response

Send Audio

Endpoint

Headers

Path Parameters

Request Body

Request Examples

Response

List Audio

Endpoint

Headers

Query Parameters

Request Example

Response

Get Audio

Endpoint

Headers

Path Parameters

Request Example

Response

Delete Audio

Endpoint

Headers

Path Parameters

Request Example

Response

Common Workflows

Next Steps