Music Assistant Server REST API Documentation: A Complete Guide to Endpoints and Integration

The Music Assistant server exposes a versioned REST API built on FastAPI that operates under the /api/v1 prefix, handling authentication via optional Bearer tokens and routing requests through music_assistant/api/routes.py to core handlers in music_assistant/api/rest.py.

The music-assistant/server repository provides a robust music management platform that exposes its functionality through a comprehensive REST API. Built on the FastAPI framework, this API enables programmatic control over players, library searches, and playback operations. The architecture follows a clean separation of concerns, with endpoint definitions, request validation, and core business logic distributed across specific modules.

Architecture Overview

The API implementation follows a layered architecture that separates concerns between HTTP handling, business logic, and data validation.

Application Entry Point: The music_assistant/server.py file creates the FastAPI application, loads configuration from music_assistant/config.py, and mounts the API router under the versioned prefix /api/v1.

API Routing Layer: All REST endpoints are declared in music_assistant/api/routes.py. This module defines the URL structure and implements the optional authentication dependency that checks for Authorization: Bearer <token> headers when the server runs with the --api-token flag.

Request Handling: The music_assistant/api/rest.py file contains the endpoint handler implementations. These handlers validate incoming requests using Pydantic models and forward calls to the central MusicAssistant core.

Core Service: The MusicAssistant class in music_assistant/mass.py orchestrates providers, players, database operations, and background tasks. API commands register here before execution.

Data Models: Request and response schemas live in music_assistant/api/models.py, ensuring type safety through Pydantic validation.

Authentication and Security

Authentication is optional depending on server configuration. When started with the --api-token argument, the server requires all requests to include an Authorization: Bearer <token> header. The FastAPI dependency that performs this validation resides in music_assistant/api/routes.py, filtering unauthorized requests before they reach the handler logic.

Core API Endpoints and Operations

Player Management

Retrieve all available media players connected to the system using the players endpoint.

curl -s -H "Authorization: Bearer YOUR_API_TOKEN" \
     http://localhost:8095/api/v1/players

Library Search

Search the music library using query parameters. The search endpoint accepts URL-encoded query strings to filter tracks, albums, and artists.

curl -s -G -H "Authorization: Bearer YOUR_API_TOKEN" \
    --data-urlencode "query=Beatles" \
    http://localhost:8095/api/v1/search

Playback Control

Control playback operations through dedicated endpoints for queueing, playing, and state monitoring.

Queue a track on a specific player by sending a JSON payload with track and player identifiers:

curl -s -X POST -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -d '{"track_id":"track_01","player_id":"sonos_livingroom"}' \
    http://localhost:8095/api/v1/playback/queue

Start playback on a designated player:

curl -s -X POST -H "Authorization: Bearer YOUR_API_TOKEN" \
    http://localhost:8095/api/v1/playback/play?player_id=sonos_livingroom

Retrieve current playback state to monitor progress and status:

curl -s -H "Authorization: Bearer YOUR_API_TOKEN" \
    http://localhost:8095/api/v1/playback/state?player_id=sonos_livingroom

Data Validation and Models

The API enforces strict type validation through Pydantic models defined in music_assistant/api/models.py. When requests arrive at the handlers in music_assistant/api/rest.py, FastAPI automatically validates the payload structure against these schemas before passing data to the MusicAssistant core. This ensures that only properly formatted requests reach the underlying music management logic.

Versioning Strategy

The API follows a versioned design pattern centered on the /api/v1 prefix. Adding support for a new API version requires creating a separate router module without modifying existing endpoint handlers. This approach maintains backward compatibility, allowing existing clients to continue operating against older versions while new implementations leverage updated endpoints.

Summary

• The REST API is built on FastAPI and accessible under the /api/v1 prefix as defined in music_assistant/server.py.
• Optional authentication using Bearer tokens is enforced via dependencies in music_assistant/api/routes.py when the --api-token flag is active.
• Request handling flows from music_assistant/api/routes.py to music_assistant/api/rest.py, then to the core MusicAssistant class in music_assistant/mass.py.
• Pydantic models in music_assistant/api/models.py provide request validation and response serialization.
• Practical endpoints cover player management (/api/v1/players), library search (/api/v1/search), and playback control (/api/v1/playback/*).
• The architecture supports seamless versioning by creating new router modules without disrupting existing client integrations.

Frequently Asked Questions

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

The API operates under the versioned prefix /api/v1. By default, the server runs on port 8095, making the full base URL http://localhost:8095/api/v1 followed by specific endpoint paths.

Is authentication required for all API endpoints?

Authentication is optional. When you start the server with the --api-token parameter, you must include Authorization: Bearer <token> in all requests. Without this flag, the FastAPI dependency in music_assistant/api/routes.py bypasses token validation, allowing open access.

How does the API validate incoming request data?

The API uses Pydantic models defined in music_assistant/api/models.py to enforce type safety. Handler functions in music_assistant/api/rest.py use these models as dependency annotations, triggering automatic validation before the request reaches the core MusicAssistant logic.

Where should I add new API versions?

New versions require creating a distinct router module following the pattern established in music_assistant/api/routes.py. Mount this new router under a version-specific prefix (such as /api/v2) in music_assistant/server.py. This approach preserves existing endpoints while allowing iterative API improvements.

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