Complete Guide to Music Assistant Server API Endpoints

Music Assistant Server exposes a comprehensive HTTP API built on aiohttp that exposes all functionality—from player control to music library management—through JSON-RPC-style endpoints under the /api base path.

The Music Assistant Server (music-assistant/server) provides a unified media control layer for your home audio ecosystem. Developers can interact with the server programmatically through its well-organized REST API, which maps internal controller methods to accessible HTTP endpoints using the @api_command decorator. This guide covers every public endpoint category, source file locations, and practical implementation examples.

How the API Architecture Works

The API follows a decorator-based registration pattern that automatically exposes internal methods as HTTP endpoints.

The @api_command Decorator Pattern

In music_assistant/helpers/webserver.py, the Webserver class implements an aiohttp application that dynamically routes incoming requests. Controllers register methods using the @api_command decorator, which accepts parameters for the path string (e.g., "music/search"), optional role restrictions, and authentication requirements. At startup, the server iterates through decorated methods and binds them to the base URL, typically http://<host>:<port>/api.

Authentication and Authorization

All endpoints require Bearer token authentication via the Authorization: Bearer <token> header. The auth/login endpoint in music_assistant/controllers/webserver/auth.py (line 1122) issues tokens, while role-based access control restricts administrative functions like user management and task cancellation to privileged accounts.

Core Server Endpoints

These endpoints provide server metadata and provider management capabilities.

Server Information and Status

The info endpoint (defined in music_assistant/mass.py, line 306) returns general server information including version, uptime, and configuration. To retrieve loaded provider modules, use the providers endpoint (line 334). For detailed provider metadata, providers/manifests (line 320) lists all manifest files, while providers/manifests/get (line 325) retrieves specific provider configurations.

System Logging

Administrators can retrieve server logs through the logging/get endpoint (line 360 in music_assistant/mass.py), which requires admin privileges to access historical log data.

Authentication Endpoints

User and token management endpoints reside in music_assistant/controllers/webserver/auth.py:

• auth/login (line 1122): Authenticate credentials and receive a Bearer token
• auth/logout (line 1547): Invalidate the current session token
• auth/me (line 1394): Retrieve the current user profile and permissions
• auth/users (line 1005): List all system users (admin only)
• auth/user/create (line 1300): Create new user accounts (admin only)
• auth/token/create (line 1264): Issue long-lived tokens for service accounts

Player Control Endpoints

The player controller (music_assistant/controllers/players/controller.py) manages audio output devices and playback state.

Player State Management

• players/all (line 319): Get a summary of all player states and capabilities
• players/get (line 371): Retrieve detailed state for a specific player ID

Playback Commands

Control active playback through these command endpoints:

• players/cmd/play (line 506): Start or resume playback
• players/cmd/pause (line 529): Pause current playback
• players/cmd/volume_set (line 679): Set volume level (0-100 range)
• players/cmd/group (line 1296): Create synchronized player groups

Additional commands include stop, next, previous, power, and mute operations.

Player Queue Management

Queue operations are handled in music_assistant/controllers/player_queues.py:

• player_queues/all (line 315): List all active queue objects across players
• player_queues/play_media (line 486): Add media to a queue and immediately start playback
• player_queues/skip (line 811): Advance to the next queue item
• player_queues/clear (line 599): Remove all items from a specific queue

The controller also supports shuffle, repeat, and playback speed adjustments through related endpoints.

Music Library Endpoints

The music controller (music_assistant/controllers/music.py) provides the bulk of media interaction:

Search and Discovery

• music/search (line 321): Global search across all configured providers and local library
• music/browse (line 591): Navigate provider hierarchies (folders, playlists, categories)
• music/track_by_name (line 1562): Search for specific tracks by exact name and artist

Item Retrieval and Management

• music/item (line 983): Retrieve a single media item by its unique ID
• music/item_by_uri (line 873): Resolve any Music-Assistant-compatible URI to a media object
• music/library/add_item (line 1145): Add media to the local library with optional overwrite behavior
• music/add_provider_mapping (line 1979): Manually map library items to specific provider sources

User Interactions

• music/favorites/add_item (line 1042): Add items to the user's favorites collection
• music/recently_played_items (line 674): Retrieve playback history
• music/mark_played (line 1348): Update play counts and last-played timestamps

Library Maintenance

• music/sync (line 261): Trigger synchronization for selected providers or media types

System Management Endpoints

Background Tasks

The tasks controller (music_assistant/controllers/tasks/controller.py) monitors server operations:

• tasks/list (line 97): Enumerate all background tasks and their status
• tasks/run (line 116): Execute specific tasks immediately (admin only)
• tasks/cancel (line 150): Terminate running tasks (admin only)

Localization and Analysis

• translations/locales (line 65 in music_assistant/controllers/translations/__init__.py): Return supported UI locale codes
• audio_analysis/coverage (line 596 in music_assistant/controllers/streams/audio_analysis.py): Retrieve audio analysis coverage statistics

Practical API Usage Examples

The following Python examples demonstrate common interactions with the Music Assistant API:

import requests

BASE = "http://localhost:8095/api"
TOKEN = "YOUR_AUTH_TOKEN"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

# 1. Search across all providers and library

response = requests.post(
    f"{BASE}/music/search",
    json={"search_query": "Beatles", "media_types": ["track"], "limit": 10},
    headers=HEADERS
)
tracks = response.json().get("tracks", [])

# 2. Retrieve all player states

players = requests.get(f"{BASE}/players/all", headers=HEADERS).json()

# 3. Start playback on a specific player

payload = {"player_id": "my_sonos", "item_id": "12345", "media_type": "track"}
requests.post(f"{BASE}/players/cmd/play", json=payload, headers=HEADERS)

# 4. Add track to favorites

requests.post(
    f"{BASE}/music/favorites/add_item",
    json={"item": "music://library/track/12345"},
    headers=HEADERS
)

Summary

• Music Assistant Server exposes a JSON-RPC-style HTTP API running on aiohttp under the /api base path
• Endpoints are dynamically registered via the @api_command decorator found in music_assistant/helpers/webserver.py
• Authentication uses Bearer tokens obtained from auth/login in music_assistant/controllers/webserver/auth.py
• Player control endpoints reside in music_assistant/controllers/players/controller.py and support comprehensive playback management
• Music library operations are centralized in music_assistant/controllers/music.py with endpoints for search, browsing, and favorites management
• Administrative functions like logging and task management require appropriate role permissions

Frequently Asked Questions

What is the base URL for Music Assistant Server API endpoints?

The base URL follows the format http://<host>:<port>/api where the default port is 8095. All endpoints are relative to this path, so the complete URL for player commands would be http://localhost:8095/api/players/cmd/play.

How does authentication work with the Music Assistant API?

The API uses Bearer token authentication. First call auth/login with username and password to receive a token, then include that token in the Authorization: Bearer <token> header for all subsequent requests. Some endpoints like auth/users and tasks/cancel additionally require admin role privileges.

Can I control multiple players simultaneously through the API?

Yes. While individual player commands target specific player IDs through endpoints like players/cmd/play, you can create synchronized groups using the players/cmd/group endpoint (line 1296 in music_assistant/controllers/players/controller.py). Once grouped, commands sent to the group player ID affect all members simultaneously.

Where are the music search and library endpoints defined?

The music-related endpoints are implemented in music_assistant/controllers/music.py. This includes global search (music/search, line 321), item retrieval (music/item, line 983), library synchronization (music/sync, line 261), and favorites management (music/favorites/add_item, line 1042).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}