Roon Music Controller#

Your Roon system is controlled via a REST API running in LCX container on Proxmox server.

API Base#

text

http://roonext2.home:3001/api

CRITICAL: How to make API calls#

GET:

bash

curl -s 'http://roonext2.home:3001/api/status'

POST:

bash

curl -X POST http://roonext2.home:3001/api/find-and-play \
  -H "Content-Type: application/json" \
  -d '{
    "zone_id": "YOUR_ZONE_ID",
    "query": "stool pigeon",
    "type": "Tracks",
    "action": "Play Now"
  }'

Zones#

Replace this table with your own zones. Get them by calling /api/zones.

ZoneIDSchlafzimmer1601dcef8115529daf4cd6807753971fae3eWohnzimmer160124b4c2dcc52aa8478e05110f7ed25120

How to find your zone IDs:

bash

curl -s 'http://roonext2.home:3001/api/zones'

Endpoints#

MethodPathPurposeGET/api/statusAll zones, playback state, now playingGET/api/zonesZone list with IDsGET/api/search?q=<query>[&type=Tracks|Albums|Artists]Search library + TIDALPOST/api/find-and-playMain play endpoint — search + play in one sessionPOST/api/transportPlayback control (play/pause/skip etc.)POST/api/volumeVolume controlGET/api/queue/<zone_id>View current queuePOST/api/playlistQueue multiple tracks in order (save as playlist in Roon app)GET/api/inspect?q=<query>Debug: show Roon's exact action names for a trackPOST/api/shuffleEnable or disable shuffle for a zonePOST/api/play-albumPlay an entire album — natively queues all tracks in order

play-album (album playback)#

Use this endpoint when the user asks to play an album. Do NOT use find-and-play for albums — it only plays the first track.

json

{ "zone_id": "...", "query": "Artist Album", "action": "Play Now" }

Searches for the album, navigates Roon's full browse hierarchy (Search → Albums → Album page → Play Album → action), and triggers album-level playback. All tracks are queued natively in the correct album order.

Supports the same action strings: Play Now, Queue, Add Next, Start Radio.

bash

curl -X POST http://roonext2.home:3001/api/play-album \
  -H "Content-Type: application/json" \
  -d '{
    "zone_id": "YOUR_ZONE_ID",
    "query": "white city a novel",
    "action": "Play Now"
  }'

find-and-play (single track playback)#

json

{ "zone_id": "...", "query": "...", "type": "Tracks", "action": "Play Now" }

CRITICAL — Roon's exact action labels#

These are the real strings Roon uses internally. Wrong names silently fall back to Play Now.

Want to...Use this stringPlay immediately (clears queue)Play NowAdd to end of queueQueue ← NOT "Add to Queue"Play after current trackAdd Next ← NOT "Play Next"Start Roon RadioStart Radio

transport#

json

{ "zone_id": "...", "action": "next" }

Valid actions: play, pause, stop, next, previous, toggle_play_pause

shuffle#

json

{ "zone_id": "...", "shuffle": true }

Set shuffle to true to enable, false to disable.

bash

curl -s -X POST http://roonext2.home3001/api/shuffle \
  -H 'Content-Type: application/json' \
  -d '{"zone_id": "1601dcef8115529daf4cd6807753971fae3e", "shuffle": true}'

volume#

json

{ "zone_id": "...", "how": "absolute", "value": 40 }

Range 0–100. how: absolute, relative, relative_step

Playlist pattern#

Option A — /api/playlist (recommended for multi-track lists)#

Queues all tracks in one API call. First track plays immediately, rest are queued. To save as a permanent Roon playlist: Queue → ⋮ → Save Queue as Playlist.

Note: Roon's Extension API does not expose "Add to Playlist" to third-party extensions — only playback actions are available. The queue-then-save workflow is the supported path.

json

POST /api/playlist
{
  "name": "My 1988 Mix",
  "zone_id": "YOUR_ZONE_ID",
  "tracks": [
    { "query": "Song One Artist One" },
    { "query": "Song Two Artist Two" },
    { "query": "Song Three Artist Three" }
  ]
}

bash

curl -s -X POST http://roonext2.home:3001/api/playlist \
  -H 'Content-Type: application/json' \
  -d '{"name":"My Playlist","zone_id":"YOUR_ZONE_ID","tracks":[{"query":"Song One Artist"},{"query":"Song Two Artist"}]}'

Option B — individual find-and-play calls (for short lists or fine control)#

First track → Play Now (starts playback, clears existing queue). All subsequent tracks → Queue. Use delay 2 between calls.

bash

ZONE="YOUR_ZONE_ID"
API="http://roonext2.home:3001/api/find-and-play"

tracks=(
  "Song One Artist One|Play Now"
  "Song Two Artist Two|Queue"
  "Song Three Artist Three|Queue"
)

for track in "${tracks[@]}"; do
  query="${track%%|*}"
  action="${track##*|}"
  curl -s -X POST "$API" \
    -H 'Content-Type: application/json' \
    -d "{\"zone_id\":\"$ZONE\",\"query\":\"$query\",\"type\":\"Tracks\",\"action\":\"$action\"}"
  sleep 2
done

Your library and taste profile#

Edit this section to describe your own library and musical taste. Cowork uses this to make smart recommendations and playlist choices on your behalf.

text

YOUR_STREAMING_SERVICE is connected — any track can be played.

Local library includes:
- Artist — albums

Taste profile: describe your taste here so Cowork can recommend music you'll enjoy.

Roon authorisation#

If the API returns "Not connected to Roon Core", you need to re-authorise:

Roon → Settings → Extensions → Enable "Cowork Controller"

Learnings#

verify.artist_match – check that the artist of a track or album matches the requested artist before adding to the queue. This prevents mismatches like Bobbi Humphrey for a Commodores request.
Embedding future learnings here ensures they are only loaded when the roon‑controller skill is used.