Music Assistant API Schema Versioning Compatibility: A Complete Technical Guide

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, 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 (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 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 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) 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 test suite verifies that these guards properly reject incompatible schema versions rather than allowing silent failures.

Practical Implementation Examples

Checking Version via HTTP

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

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

# 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 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 for HTTP clients and music_assistant/controllers/webserver/websocket_client.py for WebSocket connections.
• Strict Validation: Both server (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 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. 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, 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.

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