# Complete Guide to Music Assistant Server API Endpoints

> Explore Music Assistant Server API endpoints for player control and library management. Access comprehensive HTTP API functionality via JSON-RPC style endpoints under the /api path.

- Repository: [Music Assistant/server](https://github.com/music-assistant/server)
- Tags: api-reference
- Published: 2026-06-15

---

**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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/translations/__init__.py)): Return supported UI locale codes
- **`audio_analysis/coverage`** (line 596 in [`music_assistant/controllers/streams/audio_analysis.py`](https://github.com/music-assistant/server/blob/main/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:

```python
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`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/webserver.py)
- Authentication uses Bearer tokens obtained from `auth/login` in [`music_assistant/controllers/webserver/auth.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/webserver/auth.py)
- Player control endpoints reside in [`music_assistant/controllers/players/controller.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/players/controller.py) and support comprehensive playback management
- Music library operations are centralized in [`music_assistant/controllers/music.py`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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).