Local API

Access#Link to “Access”

The Local API runs with the Companion server: Settings → Integrations → “Companion & Local API” → “Enable Companion”. That is where you find “Address” and “Pairing token”. By default the server can only be reached on this computer (loopback).

Read the library#Link to “Read the library”

GET /api/library
Authorization: Bearer <Token>

The response contains public metadata, revisions of tracks and playlists and resolved smartlists. Pair again after a server restart.

Changes#Link to “Changes”

First turn on “Allow mobile changes and player control”. Every change needs the current revision from GET:

POST /api/changes
Authorization: Bearer <Token>
Content-Type: application/json

{
  "type": "track",
  "id": "Track-ID aus GET",
  "baseRevision": "Revision aus GET",
  "patch": { "rating": 4, "notes": "Peak-Time", "tags": ["Audience:Club"] }
}

Allowed track fields: title, artist, album, genre, bpm, key, tags, rating, energy, notes, favorite. An outdated revision returns 409 and changes nothing; if write access is off, 405 is returned. Successful changes appear on the desktop and can be undone there.

Control the player#Link to “Control the player”

POST /api/control

{ "action": "play", "trackId": "track ID from GET" }

Actions: toggle, pause, next, previous, jump-forward (+8 beats), jump-back (−8 beats), play and enqueue. The desktop player must be open.