Partner API - Musique App

Overview

The Musique Partner API allows you to programmatically manage audio content and send messages to your locations. Built with a stateless architecture and token-based authentication, the API provides a secure and scalable way to integrate Musique into your existing systems.

Key Features

Token Authentication

Secure API key authentication using X-API-Key header for all requests.

Audio Management

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

Broadcast & Single Send

Send audio to multiple locations or target specific stores.

Stateless Architecture

Reduced server load with efficient token-based authentication.

Use Cases

The Partner API is ideal for:

Multi-location Businesses - Manage audio across franchise networks
Marketing Platforms - Automate promotional message distribution
Integration Partners - Embed Musique functionality into your platform
Custom Applications - Build tailored audio management solutions

Getting Started

1. Request Integration Access

Contact Musique support to request Partner API access. You’ll need to provide:

Your company information
External ID (your internal identifier)
Company Token (provided by Musique)
Use case description

2. Generate Your API Token

Once approved, generate your authentication token:

curl -X POST https://api.musique.app/api/integration/auth \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "your-external-id",
    "companyToken": "your-company-token"
  }'

Store your API token securely. Never expose it in client-side code or public repositories.

3. Make Your First Request

Test your token with a health check:

curl -X GET https://api.musique.app/api/integration/health \
  -H "X-API-Key: msk_live_1234567890abcdef"

Authentication

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

X-API-Key: msk_live_1234567890abcdef

Token Management

Token Format

Tokens follow the format: msk_[environment]_[random_string]

msk_live_ - Production tokens
msk_test_ - Test/sandbox tokens (future)

Token Security

Tokens are hashed in the database for security
Each token is associated with a specific user and external ID
Tokens can be revoked at any time
No expiration by default (expires_at: null)

Revoke a Token

If a token is compromised, revoke it immediately:

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

Then generate a new token and update your systems.

Core Concepts

External ID Mapping

Your External ID is your internal identifier for locations or users. Musique maps these to internal user IDs, allowing you to:

Use your own identification system
Maintain consistency across platforms
Target specific locations using your identifiers

Example Mapping:

External ID    →    Musique User ID    →    Token
loja1         →    mp1                →    XXXX
loja2         →    mp2                →    YYYY
loja3         →    mp3                →    ZZZZ

Single vs Broadcast Send

Single Send
Broadcast

Send audio to specific locations by providing exact External IDs:

POST /api/integration/{audioId}/send
{
  "externalIds": ["loja1", "loja2"]
}

Use when targeting specific stores or testing before wider rollout.

Send audio to all users associated with your token:

POST /api/integration/{audioId}/send
{
  "externalIds": []
}

Use for company-wide announcements or messages for all locations.

Rate Limits

API requests are rate-limited to ensure fair usage and system stability:

Per Minute: 100 requests
Per Hour: 1,000 requests
Audio Upload: Varies by plan

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 640
X-RateLimit-Reset: 1642153200

Check the /api/integration/limits endpoint to view your current usage and limits.

API Endpoints Overview

Audio Management

Create Audio

Upload new audio files to your library.

Send Audio

Send audio messages to specific locations.

List Audio

Retrieve all audio files in your library.

Get Audio

Get specific audio file by ID.

Delete Audio

Remove audio files from your library.

Authentication

Generate Token

Create new API authentication token.

Revoke Token

Invalidate existing authentication token.

Test Token

Verify token validity and permissions.

System

Health Check

Check API system health and status.

API Information

Get API version and configuration details.

Usage Logs

Retrieve your API usage logs.

Rate Limits

Check current usage and limits.

Response Format

All API responses follow a consistent JSON format:

Success Response

{
  "message": "Operation successful",
  "data": {
    // Response data here
  }
}

Error Response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again in 60 seconds.",
    "type": "client_error",
    "documentation_url": "https://docs.musique.app/errors#rate_limit_exceeded",
    "request_id": "req_123456789",
    "retry_after": 60
  }
}

Common Error Codes

Authentication Errors

invalid_token - Token is invalid or malformed
expired_token - Token has expired
insufficient_scope - Token lacks required permissions

Resource Errors

not_found - Requested resource doesn’t exist
already_exists - Resource with that ID already exists
conflict - Request conflicts with current state

Validation Errors

invalid_format - Request data format is incorrect
missing_field - Required field is missing
out_of_range - Value exceeds allowed range

Rate Limit Errors

rate_limit_exceeded - Too many requests
quota_exceeded - Monthly quota exceeded

Best Practices

Error Handling

Always handle errors gracefully. Use request_id when contacting support.

Rate Limiting

Implement exponential backoff when receiving 429 responses.

Token Security

Store tokens securely using environment variables or secret management.

Logging

Log all API requests and responses for debugging and audit purposes.

Testing

Test with single locations before broadcasting to all stores.

Monitoring

Monitor your usage via /api/integration/limits endpoint.

Roadmap

Phase 1 - MVP (Current)

✅ API Key Authentication
✅ Audio CRUD operations
✅ Health endpoint
✅ Basic error handling

Phase 2 - Short-term

🔄 Rate limiting headers
🔄 Standardized error format
🔄 Request IDs for tracking
🔄 Pagination support
🔄 OpenAPI specification

Phase 3 - Medium-term

📋 Webhooks for async notifications
📋 Sandbox environment
📋 Audit logs
📋 Language-specific SDKs
📋 Usage analytics dashboard

Phase 4 - Enterprise

📋 OAuth 2.0 authentication
📋 mTLS support
📋 Advanced webhook features
📋 Batch operations
📋 SLA guarantees

Support

Need Help?

Technical Support: [email protected]
API Documentation: docs.musique.app/api-reference
Status Page: status.musique.appWhen contacting support, include:

Your External ID
Request ID (from error response)
Timestamp of the issue
Error message and code

Next Steps

API Reference

Explore detailed endpoint documentation with request/response examples.

Quick Start Guide

Learn how to create and manage audio content.

Documentation

Quickstart

Learn

API Reference

​Overview

​Key Features

Token Authentication

Audio Management

Broadcast & Single Send

Stateless Architecture

​Use Cases

​Getting Started

​1. Request Integration Access

​2. Generate Your API Token

​3. Make Your First Request

​Authentication

​Token Management

​Core Concepts

​External ID Mapping

​Single vs Broadcast Send

​Rate Limits

​API Endpoints Overview

​Audio Management

Create Audio

Send Audio

List Audio

Get Audio

Delete Audio

​Authentication

Generate Token

Revoke Token

Test Token

​System

Health Check

API Information

Usage Logs

Rate Limits

​Response Format

​Success Response

​Error Response

​Common Error Codes

​Best Practices

Error Handling

Rate Limiting

Token Security

Logging

Testing

Monitoring

​Roadmap

​Phase 1 - MVP (Current)

​Phase 2 - Short-term

​Phase 3 - Medium-term

​Phase 4 - Enterprise

​Support

Need Help?

​Next Steps

API Reference

Quick Start Guide

Overview

Key Features

Use Cases

Getting Started

1. Request Integration Access

2. Generate Your API Token

3. Make Your First Request

Authentication

Token Management

Core Concepts

External ID Mapping

Single vs Broadcast Send

Rate Limits

API Endpoints Overview

Audio Management

Authentication

System

Response Format

Success Response

Error Response

Common Error Codes

Best Practices

Roadmap

Phase 1 - MVP (Current)

Phase 2 - Short-term

Phase 3 - Medium-term

Phase 4 - Enterprise

Support

Next Steps