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

> Explore the Music Assistant Server REST API documentation. Learn how to integrate with endpoints, authentication, and handlers with this comprehensive guide for developers.

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

---

**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`](https://github.com/music-assistant/server/blob/main/music_assistant/api/routes.py) to core handlers in [`music_assistant/api/rest.py`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/music_assistant/server.py) file creates the FastAPI application, loads configuration from [`music_assistant/config.py`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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.

```bash
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.

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/music-assistant/server/blob/main/music_assistant/api/models.py). When requests arrive at the handlers in [`music_assistant/api/rest.py`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/music_assistant/server.py).
- **Optional authentication** using Bearer tokens is enforced via dependencies in [`music_assistant/api/routes.py`](https://github.com/music-assistant/server/blob/main/music_assistant/api/routes.py) when the `--api-token` flag is active.
- Request handling flows from [`music_assistant/api/routes.py`](https://github.com/music-assistant/server/blob/main/music_assistant/api/routes.py) to [`music_assistant/api/rest.py`](https://github.com/music-assistant/server/blob/main/music_assistant/api/rest.py), then to the core `MusicAssistant` class in [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py).
- **Pydantic models** in [`music_assistant/api/models.py`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/music_assistant/api/models.py) to enforce type safety. Handler functions in [`music_assistant/api/rest.py`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/music_assistant/api/routes.py). Mount this new router under a version-specific prefix (such as `/api/v2`) in [`music_assistant/server.py`](https://github.com/music-assistant/server/blob/main/music_assistant/server.py). This approach preserves existing endpoints while allowing iterative API improvements.