Skip to main content

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.

The Musique Partner API gives you programmatic control over audio uploads, library management, and device broadcasts — built for retailers, franchises, and multi-unit businesses that need to manage audio at scale.

​
Key Features

Token Authentication

Secure API key authentication using the X-API-Key header on every request.

Audio Management

Upload, retrieve, delete, and broadcast audio files programmatically.

Broadcast & Targeted Send

Send audio to all locations at once, or target specific stores by External ID.

OpenAPI Spec

Interactive playground and full spec available in the API Reference.

​
Use Cases

  • Multi-location businesses — Manage audio across franchise networks from a single integration
  • Marketing platforms — Automate promotional message distribution by store or region
  • Integration partners — Embed Musique functionality into your own platform
  • Custom applications — Build tailored audio management solutions

​
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.
Store your API token securely. Never expose it in client-side code or public repositories. Use environment variables or a secret manager.

​
2. Make Your First Request

Test your token with a health check: 
curl https://api.musique.app/api/v1/integration/health \
  -H "X-API-Key: msk_prod_1234567890abcdef"

​
3. Upload and Send Audio

curl -X POST https://api.musique.app/api/v1/integration/audio \
  -H "X-API-Key: msk_prod_1234567890abcdef" \
  -F "file=@announcement.mp3"

​
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.
PartDescription
companyPrefixIdentifies the partner company (e.g. msk)
environmentPrefixprod for production, dev for development
hashTokenUnique hash per user
  • 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 immediately to revoke it

​
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

Send audio to specific locations by listing their External IDs:
POST /api/v1/integration/audio/{id}/send
{
  "externalIds": ["store_001", "store_042"]
}
Use this for regional campaigns or testing before a wider rollout.

​
Rate Limits

Coming soon — Rate limit documentation and per-key usage endpoints are under development. See the Rate Limits page for planned specs.
Standard limits per API key:
WindowLimit
Per minute100 requests
Per hour1,000 requests
Per day10,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.

​
API Endpoints

​
Audio

List Audio

Retrieve all audio files in your library.

Upload Audio

Upload a new MP3 file to your library.

Get Audio

Retrieve a specific audio file by ID.

Send Audio

Broadcast audio to devices by External ID.

​
System

API Info

Get API name, version, and documentation URL.

Health Check

Check API health and service status.

​
Response Format

All responses return JSON. Errors follow a consistent structure: 
{
  "error": {
    "code": "invalid_token",
    "message": "Invalid or expired API token",
    "type": "authentication_error"
  }
}
See the Errors page for a full list of codes and handling examples.

​
Best Practices

Error Handling

Handle all error types explicitly. See the Errors guide for per-status examples.

Rate Limiting

Implement exponential backoff on 429 responses. Start at 1 second and double each retry.

Token Security

Store tokens in environment variables or a secret manager. Rotate immediately if exposed.

Test Before Broadcasting

Always test with a single externalId before sending to all locations.

​
Roadmap

​
Phase 1 — Complete

  • API key authentication
  • Audio CRUD operations
  • Health and info endpoints
  • OpenAPI specification with interactive playground

​
Phase 2 — In Progress

  • Rate limiting headers
  • Pagination support
  • Request IDs for support tracking

​
Phase 3 — Planned

  • Webhooks for async notifications
  • Sandbox environment
  • Audit logs
  • Language-specific SDKs

​
Phase 4 — Enterprise

  • OAuth 2.0
  • Batch operations
  • SLA guarantees

​
Support

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

API Reference

Full endpoint docs with interactive playground.

Quick Messages Guide

Learn how to create and manage audio content in the Musique dashboard.