Music Assistant provides a powerful API to control your music library, manage players, and stream audio. Whether you’re building a custom interface, integrating with home automation, or creating a music app, the API gives you complete control.
The API documentation is automatically generated and available at http://YOUR_MA_SERVER_IP:8095/api-docs
Examples
Section titled “Examples”Play a random track from a playlist
Save current queue as a playlist
Get All Available Player Settings
curl --location 'http://192.168.1.1:8095/api' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR......I' \--data '{ "message_id": "1", "command": "config/players/get", "args": { "player_id": "RINCON_48A6B820191201400" }}'rest_command: ma_get_player_settings: url: http://192.168.1.1:8095/api method: POST headers: accept: "application/json, text/html" authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR......I" payload: > { "message_id": "1", "command": "config/players/get", "args": { "player_id": "{{ player_id }}" } } content_type: 'application/json; charset=utf-8'Set One or More Player Settings
curl --location 'http://192.168.1.1:8095/api' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR......I' \--data '{ "message_id": "1", "command": "config/players/save", "args": { "player_id": "RINCON_48A6B820191201400", "values": { "airplay_mode": true } }}'rest_command: ma_set_player_settings: url: http://192.168.1.1:8095/api method: POST headers: accept: "application/json, text/html" authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR......I" payload: > { "message_id": "1", "command": "config/players/save", "args": { "player_id": "b8:27:eb:8a:b8:8e", "values": { "crossfade": true } } } content_type: 'application/json; charset=utf-8'Add Item to Favorites
item needs to be a URI or share URL
curl --location 'http://192.168.1.1:8095/api' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR......I' \--data '{ "message_id": "1", "command": "music/favorites/add_item", "args": { "item": "spotify://track/1234567" }}'Get Album Tracks
curl --location 'http://192.168.1.1:8095/api' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR......I' \--data '{ "message_id": "1", "command": "music/albums/album_tracks", "args": { "item_id": "1", "provider_instance_id_or_domain": "library", "in_library_only": true }}'rest_command: ma_album_tracks: url: http://192.168.1.1:8095/api method: POST headers: accept: "application/json, text/html" authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR......I" payload: > { "message_id": "1", "command": "music/albums/album_tracks", "args": { "item_id": "{{ item_id }}", "provider_instance_id_or_domain": "{{ provider_instance_id_or_domain }}", "in_library_only": "{{ in_library_only }}" } } content_type: 'application/json; charset=utf-8'Get Full Item Details (By Providing a URI)
curl --location 'http://192.168.1.1:8095/api' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR......I' \--data '{ "message_id": "1", "command": "music/item_by_uri", "args": { "uri": "spotify://track/1234" }}'Get Recently Played Items
limit and media_types are optional
curl --location 'http://192.168.1.1:8095/api' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR......I' \--data '{ "message_id": "1", "command": "music/recently_played_items", "args": { "limit": 10, "media_types": ["track", "album"] }}'Get In Progress Items (Audiobooks, Podcast Episodes)
Return a list of the Audiobooks and PodcastEpisodes that are in progress. limit is optional
curl --location 'http://192.168.1.1:8095/api' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR......I' \--data '{ "message_id": "1", "command": "music/in_progress_items", "args": { "limit": 10 }}'Starting Sync
Start running the sync of (all or selected) musicproviders. media_types: only sync these media types. None for all. providers: only sync these provider instances. None for all.
curl --location 'http://192.168.1.1:8095/api' \--header 'Content-Type: application/json' \--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR......I' \--data '{ "message_id": "1", "command": "music/sync", "args": { "media_types": ["track", "album"], "providers": ["filesystem--1234"] }}'Refresh Playlist
rest_command: ma_refresh_playlist: url: http://192.168.1.1:8095/api method: POST headers: accept: "application/json, text/html" authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR......I" payload: > { "message_id": "1", "command": "music/playlists/playlist_tracks", "args": { "item_id": "1234", "provider_instance_or_domain": "builtin", "force_refresh": true } } content_type: 'application/json; charset=utf-8'Change crossfade state of a player
player_id can be found at the top of the individual player settings
rest_command: ma_set_player_settings: url: http://192.168.1.1:8095/api method: POST headers: accept: "application/json, text/html" authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR......I" payload: > { "message_id": "1", "command": "config/players/save", "args": { "player_id": "b8:27:eb:8a:b8:8e", "values": { "crossfade": true } } } content_type: 'application/json; charset=utf-8'Get all items in the queue
queue_id will be the same as the player_id unless the player is grouped. To confirm create a rest_command that calls player_queues/all and review the information returned. The limit defaults to 500 if you omit it. You are cautioned to not set a value greater then 500 to avoid breaking your system. The practical limit will depend on the resources available on your host. offset can also be omitted.
rest_command: ma_get_full_queue: url: http://192.168.1.1:8095/api method: POST headers: accept: "application/json, text/html" authorization: "Bearer eyJhbGciOiJIUzI1NiIsInR......I" payload: > { "message_id": "1", "command": "player_queues/items", "args": { "queue_id": "b8:27:eb:8a:b8:8e", "limit": 500, "offset": 0 } } content_type: 'application/json; charset=utf-8'