System

Overview

System endpoints provide monitoring and diagnostic capabilities for your Partner API integration. Use these to check API health, review usage logs, and track rate limit consumption.

Health Check

Verify that the API is operational and responding correctly.

Endpoint

GET /api/integration/health

Headers

X-API-Key

string

required

Your API authentication token

Request Example

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

Response

status

string

Overall API health status: healthy, degraded, or down

version

string

Current API version

timestamp

string

ISO 8601 timestamp of health check

services

object

Status of individual service components

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-20T15:30:45Z",
  "services": {
    "database": "healthy",
    "storage": "healthy",
    "messaging": "healthy"
  }
}

Use this endpoint for:

Uptime monitoring: Poll every 60 seconds to track availability
Pre-flight checks: Verify API is operational before critical operations
Incident response: Diagnose issues by checking service component status

API Information

Get details about the API version, your integration, and available features.

Endpoint

GET /api/integration

Headers

X-API-Key

string

required

Your API authentication token

Request Example

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

Response

version

string

Current API version

integration

object

Your integration details (externalId, permissions, accountType)

features

array

List of enabled features for your account

endpoints

object

Base URLs for different API resources

{
  "version": "1.0.0",
  "integration": {
    "externalId": "store_001",
    "userId": 4348,
    "permissions": [
      "audio.read",
      "audio.write",
      "audio.delete",
      "audio.send"
    ],
    "accountType": "partner",
    "createdAt": "2024-01-10T08:00:00Z"
  },
  "features": [
    "audio_upload",
    "broadcast_send",
    "scheduled_playback",
    "usage_analytics"
  ],
  "endpoints": {
    "audio": "https://api.musique.app/api/audio",
    "auth": "https://api.musique.app/api/integration/auth",
    "health": "https://api.musique.app/api/integration/health"
  }
}

Use this endpoint to:

Verify your integration configuration
Check which features are enabled for your account
Confirm API version before making calls
Display integration status in your admin dashboard

Usage Logs

Retrieve logs of your API requests including requests, responses, and errors.

Endpoint

GET /api/integration/logs

Headers

X-API-Key

string

required

Your API authentication token

Query Parameters

page

number

default:"1"

Page number for pagination

limit

number

default:"50"

Number of logs per page (max 200)

startDate

string

Filter logs from this date (ISO 8601)

endDate

string

Filter logs until this date (ISO 8601)

endpoint

string

Filter by specific endpoint (e.g., “/api/audio”)

status

string

Filter by HTTP status code or range (e.g., “200”, “4xx”, “5xx”)

method

string

Filter by HTTP method (GET, POST, DELETE)

Request Example

curl "https://api.musique.app/api/integration/logs?page=1&limit=10&status=200" \
  -H "X-API-Key: msk_live_1234567890abcdef"

Response

data

array

Array of log entries

pagination

object

Pagination metadata

{
  "data": [
    {
      "logId": "log_abc123xyz",
      "timestamp": "2024-01-20T15:22:30Z",
      "method": "POST",
      "endpoint": "/api/aud_9x8y7z6w5v4u3t/send",
      "statusCode": 200,
      "responseTime": 245,
      "requestSize": 512,
      "responseSize": 1024,
      "ipAddress": "203.0.113.45",
      "userAgent": "Node.js/18.0.0"
    },
    {
      "logId": "log_def456uvw",
      "timestamp": "2024-01-20T15:20:15Z",
      "method": "POST",
      "endpoint": "/api/audio",
      "statusCode": 201,
      "responseTime": 1823,
      "requestSize": 2048000,
      "responseSize": 512,
      "ipAddress": "203.0.113.45",
      "userAgent": "Python-requests/2.31.0"
    },
    {
      "logId": "log_ghi789rst",
      "timestamp": "2024-01-20T15:18:00Z",
      "method": "GET",
      "endpoint": "/api/audio",
      "statusCode": 200,
      "responseTime": 89,
      "requestSize": 256,
      "responseSize": 4096,
      "ipAddress": "203.0.113.45",
      "userAgent": "curl/7.68.0"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 247,
    "totalPages": 25
  }
}

Log Retention: Logs are retained for 30 days. Export logs regularly if you need longer retention.Common Uses:

Debugging integration issues
Auditing API usage
Monitoring performance
Compliance and security reviews

Rate Limits

Check your current rate limit consumption and remaining quota.

Endpoint

GET /api/integration/limits

Headers

X-API-Key

string

required

Your API authentication token

Request Example

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

Response

limits

object

Rate limit configuration for your account

usage

object

Current usage statistics

resetAt

object

Timestamps when limits reset

{
  "limits": {
    "perMinute": 100,
    "perHour": 1000,
    "perDay": 10000
  },
  "usage": {
    "perMinute": 23,
    "perHour": 347,
    "perDay": 2150
  },
  "remaining": {
    "perMinute": 77,
    "perHour": 653,
    "perDay": 7850
  },
  "resetAt": {
    "perMinute": "2024-01-20T15:24:00Z",
    "perHour": "2024-01-20T16:00:00Z",
    "perDay": "2024-01-21T00:00:00Z"
  }
}

Rate Limit Headers

All API responses include rate limit information in headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 77
X-RateLimit-Reset: 1705762440

X-RateLimit-Limit

Maximum requests allowed in the current time window (per minute).

X-RateLimit-Remaining

Number of requests remaining in the current time window.

X-RateLimit-Reset

Unix timestamp when the rate limit resets.

When you exceed rate limits, you’ll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 42 seconds.",
    "type": "rate_limit_error",
    "retryAfter": 42
  }
}

Implement exponential backoff and respect the Retry-After header.

Monitoring Best Practices

Set Up Alerts

Monitor for:

Consecutive 5xx errors
Rate limit warnings (>80% usage)
Slow response times (>2s)
Degraded health status

Log Regularly

Review logs weekly for:

Unusual traffic patterns
Failed requests (4xx, 5xx)
High response times
IP address changes

Track Performance

Monitor metrics:

Average response time
Request success rate (%)
Rate limit consumption
Error distribution

Health Checks

Implement monitoring:

Poll /health every 60s
Alert on 2+ consecutive failures
Track uptime SLA (>99.9%)
Monitor service components

Example: Complete Monitoring Setup

// monitor.js - Simple monitoring script
const API_KEY = process.env.MUSIQUE_API_KEY;
const BASE_URL = 'https://api.musique.app';

async function checkHealth() {
  try {
    const response = await fetch(`${BASE_URL}/api/integration/health`, {
      headers: { 'X-API-Key': API_KEY }
    });
    
    const data = await response.json();
    
    if (data.status !== 'healthy') {
      console.error('⚠️ API health degraded:', data);
      // Send alert to monitoring system
    } else {
      console.log('✅ API healthy');
    }
  } catch (error) {
    console.error('❌ Health check failed:', error);
    // Send alert
  }
}

async function checkRateLimits() {
  try {
    const response = await fetch(`${BASE_URL}/api/integration/limits`, {
      headers: { 'X-API-Key': API_KEY }
    });
    
    const data = await response.json();
    
    const usagePercent = (data.usage.perMinute / data.limits.perMinute) * 100;
    
    if (usagePercent > 80) {
      console.warn(`⚠️ Rate limit usage high: ${usagePercent.toFixed(1)}%`);
    }
  } catch (error) {
    console.error('❌ Rate limit check failed:', error);
  }
}

// Run every 60 seconds
setInterval(() => {
  checkHealth();
  checkRateLimits();
}, 60000);

Troubleshooting

High Error Rates

Symptoms: Seeing many 4xx or 5xx errors in logsCommon causes:

Invalid request format (400)
Authentication issues (401)
Rate limits exceeded (429)
Server issues (5xx)

Solutions:

Review logs: GET /api/integration/logs?status=4xx
Check token validity: POST /api/integration/test
Monitor rate limits: GET /api/integration/limits
Implement retry logic with exponential backoff

Slow Response Times

Symptoms: Response times >2 seconds consistentlyCommon causes:

Large file uploads
Network latency
Server load during peak hours
Inefficient request patterns

Solutions:

Check logs for responseTime field
Optimize file sizes (compress audio before upload)
Use batch operations when possible
Cache frequently accessed data

Degraded Health Status

Symptoms: Health check returns degraded or downActions:

Check service component status in health response
Review recent logs for errors
Reduce request rate temporarily
Contact support if issue persists >5 minutes

Next Steps

Authentication

Learn how to generate and manage API tokens.

Audio Endpoints

Upload and send audio files to devices.

Documentation

Quickstart

Learn

API Reference

Overview

Health Check

Endpoint

Headers

Request Example

Response

API Information

Endpoint

Headers

Request Example

Response

Usage Logs

Endpoint

Headers

Query Parameters

Request Example

Response

Rate Limits

Endpoint

Headers

Request Example

Response

Rate Limit Headers

Monitoring Best Practices

Set Up Alerts

Log Regularly

Track Performance

Health Checks

Example: Complete Monitoring Setup

Troubleshooting

Next Steps

Authentication

Audio Endpoints

Documentation

Quickstart

Learn

API Reference

​Overview

​Health Check

​Endpoint

​Headers

​Request Example

​Response

​API Information

​Endpoint

​Headers

​Request Example

​Response

​Usage Logs

​Endpoint

​Headers

​Query Parameters

​Request Example

​Response

​Rate Limits

​Endpoint

​Headers

​Request Example

​Response

​Rate Limit Headers

​Monitoring Best Practices

Set Up Alerts

Log Regularly

Track Performance

Health Checks

​Example: Complete Monitoring Setup

​Troubleshooting

​Next Steps

Authentication

Audio Endpoints

Overview

Health Check

Endpoint

Headers

Request Example

Response

API Information

Endpoint

Headers

Request Example

Response

Usage Logs

Endpoint

Headers

Query Parameters

Request Example

Response

Rate Limits

Endpoint

Headers

Request Example

Response

Rate Limit Headers

Monitoring Best Practices

Example: Complete Monitoring Setup

Troubleshooting

Next Steps