API Documentation

Build powerful music applications using the Macky Player API. Access millions of tracks, artists, playlists, and user data programmatically.

Introduction

The Macky Player API provides programmatic access to our music streaming platform. Our RESTful API allows developers to:

Stream and play music tracks
Search for songs, albums, artists, and playlists
Access user favorites and playlists
Retrieve trending and chart data
Manage user authentication
Upload and manage content (for authorized creators)

Getting Started

Base URL

https://api.mackyplayer.com/v1

Authentication

The Macky Player API uses OAuth 2.0 for authentication. You'll need to register your application to receive API credentials:

Register at Developer Portal
Obtain your Client ID and Client Secret
Request an access token using the OAuth 2.0 flow
Include the access token in your API requests

Request Format

All requests must be sent over HTTPS. The API accepts JSON payloads and returns JSON responses.

            Authorization: Bearer YOUR_ACCESS_TOKEN

Content-Type: application/json

Response Format

Successful responses return HTTP 200 with a JSON payload. Error responses include an error code and message.

            {

    "status": "success",

    "data": { ... }

}

Core Endpoints

Music Endpoints

GET /v1/music/search

Search for songs, albums, and artists

Parameters: q (query), type (song|album|artist), limit, offset

GET /v1/music/trending

Get trending tracks

Parameters: genre (optional), limit, time_range (day|week|month)

GET /v1/music/:id

Get details for a specific track

Returns: Track metadata, streaming URL, artist info

POST /v1/music/:id/play

Record a play event and get streaming URL

Parameters: session_id, quality (low|medium|high)

Artist Endpoints

GET /v1/artist/:slug

Get artist information

Returns: Bio, stats, social links, verified status

GET /v1/artist/:slug/tracks

Get tracks uploaded by an artist

Parameters: limit, offset, sort (recent|popular)

PUT /v1/artist/:slug/follow

Follow an artist (requires authentication)

DELETE /v1/artist/:slug/follow

Unfollow an artist (requires authentication)

Playlist Endpoints

GET /v1/playlists/:id

Get playlist details and tracks

POST /v1/playlists

Create a new playlist (requires authentication)

Body: title, description, public (boolean), tracks (array)

PUT /v1/playlists/:id

Update playlist (requires authentication)

DELETE /v1/playlists/:id

Delete playlist (requires authentication)

User Endpoints

GET /v1/user/me

Get current user profile (requires authentication)

GET /v1/user/me/favorites

Get user's favorited tracks (requires authentication)

PUT /v1/music/:id/favorite

Add track to favorites (requires authentication)

Rate Limiting

API requests are rate limited to ensure fair usage:

Free tier: 1,000 requests per hour
Premium tier: 10,000 requests per hour
Enterprise: Custom limits

Rate limit information is included in response headers:

            X-RateLimit-Limit: 1000

X-RateLimit-Remaining: 987

X-RateLimit-Reset: 1638360000

Error Handling

The API uses standard HTTP status codes:

200: Success
201: Created
400: Bad Request (invalid parameters)
401: Unauthorized (invalid/missing token)
403: Forbidden (insufficient permissions)
404: Not Found
429: Too Many Requests (rate limit exceeded)
500: Internal Server Error

Error responses include details:

            {

    "status": "error",

    "error_code": "INVALID_TOKEN",

    "message": "The access token is invalid or expired"

}

Pagination

List endpoints support pagination using limit and offset parameters:

GET /v1/music/search?q=rock&limit=20&offset=40

Response includes pagination metadata:

            {

    "data": [...],

    "pagination": {

      "total": 500,

      "limit": 20,

      "offset": 40,

      "has_more": true

    }

}

Filtering & Sorting

Many endpoints support filtering and sorting:

genre: Filter by music genre
year: Filter by release year
sort: Sort results (recent, popular, alphabetical)
fields: Specify which fields to return

Webhooks

Configure webhooks to receive real-time notifications for events:

New track uploaded
Track favorited
Playlist updated
User followed

API Terms of Use

Acceptable Use

You agree to:

Comply with our Terms of Service and Privacy Policy
Respect rate limits and not abuse the API
Cache responses appropriately to reduce unnecessary requests
Display proper attribution when using our data
Not reverse engineer or attempt to extract source code
Not use the API for illegal purposes or to violate rights

Content Rights

You may not:

Download music for redistribution without proper licensing
Strip or modify metadata from tracks
Use API data for training AI/ML models without permission
Scrape or aggregate data for competitive purposes

Commercial Use

Commercial API usage requires a paid subscription or partnership agreement. Contact us at api@mackyplayer.com for enterprise licensing.

API Keys and Security

Keep your API credentials secure and confidential
Do not share or publish your API keys
Rotate keys immediately if compromised
Use appropriate authentication for server-side apps

Service Level

We strive for 99.9% API uptime but do not guarantee uninterrupted service. We may perform maintenance with reasonable notice.

Changes and Deprecation

We may modify the API, add features, or deprecate endpoints. Breaking changes will be announced 90 days in advance when possible.

Support

For API support and questions:

Email: api@mackyplayer.com
Developer Portal: Developer Console
Documentation: Full API Reference
Status: API Status Page

Example Code

JavaScript (Node.js)

            const axios = require('axios');

const API_BASE = 'https://api.mackyplayer.com/v1';

const ACCESS_TOKEN = 'your_access_token';

async function searchMusic(query) {

    const response = await axios.get(`${API_BASE}/music/search`, {

      params: { q: query, limit: 10 },

      headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}` }

    });

    return response.data;

}

Python

            import requests

API_BASE = 'https://api.mackyplayer.com/v1'

ACCESS_TOKEN = 'your_access_token'

def search_music(query):

    headers = {'Authorization': f'Bearer {ACCESS_TOKEN}'}

    params = {'q': query, 'limit': 10}

    response = requests.get(f'{API_BASE}/music/search', 

                             headers=headers, params=params)

    return response.json()

API Version: 1.0 | Last updated: December 6, 2025