# Music Assistant API Schema Versioning Compatibility: A Complete Technical Guide

> Learn about Music Assistant API schema versioning compatibility. Discover how Music Assistant Server ensures seamless integration with monotonic integers and minimum version enforcement for robust applications.

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

---

**Music Assistant Server maintains compatibility through a monotonic integer version (`API_SCHEMA_VERSION`) that exposes the current schema via HTTP and WebSocket endpoints, while enforcing minimum version requirements on both server and client sides to prevent runtime errors.**

The `music-assistant/server` repository implements a strict versioning strategy to prevent runtime errors between server updates and client implementations. Understanding Music Assistant API schema versioning compatibility is essential for developers building third-party integrations or custom clients that communicate with the server's web API.

## How Music Assistant Implements API Schema Versioning

### Global Version Constants in constants.py

Located in [`music_assistant/constants.py`](https://github.com/music-assistant/server/blob/main/music_assistant/constants.py), the `API_SCHEMA_VERSION` constant (currently set to `33`) serves as the single source of truth for the entire public API surface. This value must be incremented whenever introducing breaking changes such as new required parameters, renamed fields, or modified enum values. The file also defines `MIN_SCHEMA_VERSION`, establishing the oldest schema version the server will accept from clients.

### Core Registration in mass.py

During initialization in [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py) (around line 330), the `Mass` object registers the schema version within the command-handler metadata. This registration makes the version available to internal controllers and ensures consistent exposure across all communication interfaces via `schema_version=API_SCHEMA_VERSION`.

## Where Clients Discover the Schema Version

### OpenAPI Specification Endpoint

The [`music_assistant/controllers/webserver/api_docs.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/webserver/api_docs.py) controller generates the OpenAPI specification dynamically, injecting `API_SCHEMA_VERSION` into the `info.version` field of the JSON response. Clients can query `GET /api-docs/openapi.json` to retrieve the server's current schema version before establishing authenticated sessions.

### WebSocket Handshake

For real-time connections, [`music_assistant/controllers/webserver/websocket_client.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/webserver/websocket_client.py) transmits the schema version immediately upon connection establishment. The initial payload includes a `"schema_version"` field, allowing clients to validate compatibility before sending any JSON-RPC commands.

## Compatibility Rules and Validation

### Server-Side Validation

The server enforces strict boundaries using `MIN_SCHEMA_VERSION`. When `ensure_schema_compatible()` (implemented in [`music_assistant/helpers/security.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/security.py)) receives a request with a version older than the minimum, it raises an `IncompatibleSchemaError`, returning HTTP 400 or closing the WebSocket connection. Requests with newer versions trigger validation errors for unknown required fields, while optional unknown fields are typically ignored.

### Client-Side Requirements

Clients must compare the server's reported `API_SCHEMA_VERSION` against their supported minimum. If the server's version is lower than the client requires, the client must disconnect or fall back to legacy command sets. The [`tests/controllers/music/test_music_migrations.py`](https://github.com/music-assistant/server/blob/main/tests/controllers/music/test_music_migrations.py) test suite verifies that these guards properly reject incompatible schema versions rather than allowing silent failures.

## Practical Implementation Examples

### Checking Version via HTTP

```python
import requests

def get_server_schema_version(host="localhost", port=8095):
    """Retrieve the current API schema version from the server."""
    resp = requests.get(f"http://{host}:{port}/api-docs/openapi.json")
    openapi = resp.json()
    return int(openapi["info"]["version"])

```

### WebSocket Client Compatibility Guard

```python
import websockets
import json

MIN_SUPPORTED = 30  # Client's minimum supported schema

async def connect_safe():
    async with websockets.connect("ws://localhost:8095/ws") as ws:
        # Server sends its version as the first message

        init = json.loads(await ws.recv())
        server_version = init["schema_version"]
        
        if server_version < MIN_SUPPORTED:
            raise RuntimeError(
                f"Incompatible server (schema {server_version} < {MIN_SUPPORTED})"
            )
        
        # Proceed with commands

        await ws.send(json.dumps({"command": "player/play", "args": {}}))

```

### Server-Side Compatibility Check

```python

# Simplified from music_assistant/helpers/security.py

def ensure_schema_compatible(request_version: int):
    if request_version < MIN_SCHEMA_VERSION:
        raise IncompatibleSchemaError(
            f"Client schema {request_version} below minimum {MIN_SCHEMA_VERSION}"
        )

```

## Summary

- **Single Source of Truth**: [`music_assistant/constants.py`](https://github.com/music-assistant/server/blob/main/music_assistant/constants.py) defines `API_SCHEMA_VERSION` as a global integer incremented only for breaking changes, alongside `MIN_SCHEMA_VERSION`.
- **Dual Exposure**: The version appears in [`music_assistant/controllers/webserver/api_docs.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/webserver/api_docs.py) for HTTP clients and [`music_assistant/controllers/webserver/websocket_client.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/webserver/websocket_client.py) for WebSocket connections.
- **Strict Validation**: Both server ([`music_assistant/helpers/security.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/security.py)) and clients enforce minimum version requirements to prevent silent failures and runtime errors.
- **Test Coverage**: [`tests/controllers/music/test_music_migrations.py`](https://github.com/music-assistant/server/blob/main/tests/controllers/music/test_music_migrations.py) validates that incompatible versions trigger explicit errors rather than undefined behavior.

## Frequently Asked Questions

### What happens when the server schema version is higher than my client supports?

When the server's `API_SCHEMA_VERSION` exceeds your client's maximum supported version, your client should disconnect or enter a compatibility mode using older command sets. The server will reject requests from outdated clients only if they fall below `MIN_SCHEMA_VERSION`, but newer clients attempting to use unknown fields may receive validation errors.

### Where is the minimum supported schema version defined?

The `MIN_SCHEMA_VERSION` constant is defined alongside `API_SCHEMA_VERSION` in [`music_assistant/constants.py`](https://github.com/music-assistant/server/blob/main/music_assistant/constants.py). This establishes the oldest version the server will accept, ensuring clients cannot connect using schemas that lack required security features or critical bug fixes implemented in later versions.

### How do I detect schema changes without parsing the OpenAPI spec?

During the WebSocket handshake in [`music_assistant/controllers/webserver/websocket_client.py`](https://github.com/music-assistant/server/blob/main/music_assistant/controllers/webserver/websocket_client.py), the server sends the `schema_version` as the first message. Clients can read this integer immediately upon connection to verify compatibility before sending any JSON-RPC commands, eliminating the need for a separate HTTP request.

### Are non-breaking changes reflected in the schema version?

No, `API_SCHEMA_VERSION` is only incremented for breaking changes such as renamed fields, new required parameters, or removed commands. Additive changes that don't break existing clients—like optional new fields—typically do not trigger a version bump according to the implementation in [`music_assistant/constants.py`](https://github.com/music-assistant/server/blob/main/music_assistant/constants.py).