MBXHub

Full web dashboard with library search, now playing, controls, volume, ratings, shuffle/autodj/repeat toggles. Panel visibility, order, and collapsible grouping are configurable via dashboardLayout in settings.

Search: client-side fuzzy album/artist matching + server-side track search. Albums containing matching tracks are boosted (e.g. “wonderwall” surfaces its album). Inline track expansion on album results. Explore button seeds explore.html?album=&artist=.

UPnP device description XML. Contains device info, service URLs, and presentation URL.

WS-Discovery metadata exchange endpoint. Windows sends a SOAP GetMetadata request after discovering MBXHub via UDP Probe; response includes PresentationUrl pointing to /dashboard.

HTML status dashboard with live stats: system info (version, uptime, host, modules), library counts (tracks, albums, artists, genres, playlists, podcasts), AutoQ state (status, vibe list, mood cache, auto scan), and feature flags. All data fetched client-side from existing API endpoints.

Returns system status and enabled modules (JSON)

Where truedat resolves each of its artifacts — asked of truedat itself (--paths --json), never derived by the hub, since its resolution order and host-suffixed naming are its own convention. Response: {resolvedFrom, paths:[{key,label,path,present,note}], capturedUtc, stale, staleReason}. resolvedFrom names which step chose the catalog — --moods argument means the hub pinned it via the moodsFilePath setting, anything else means truedat discovered it — which is the distinction a wrong-catalog report turns on. Absent artifacts keep their entry (present:false) rather than being omitted. truedat holds one run slot, so during a scan this returns the last good answer with stale:true and its capture time; 503 when truedat cannot be resolved and nothing is cached, 502 when its output cannot be read. Rendered as the Truedat Paths panel at the bottom of /status.

Diagnostic surface — a live “Geiger counter” for steady-state activity. Off by default; gated on diagnostics.diagEndpointEnabled = true in mbxhub.json. Returns 404 when disabled, with explanatory body.

/diag serves a self-contained HTML page that polls /diag/perf at 1 Hz from the browser and renders inline-SVG sparklines for: process CPU %, network bytes in/out, working-set / private bytes, thread count, handle count, GC gen0/1/2 collection rate. Last 120 samples (~2 min) held client-side. Server is stateless — no background timer, no ring buffer, no allocation while the page is closed.

/diag/perf returns an instant snapshot of public process counters via System.Diagnostics.Process, System.Net.NetworkInformation, and GC.CollectionCount. Fields: ts, processorMs, workingSetMB, privateMB, threadCount, handleCount, gen0/gen1/gen2, bytesIn, bytesOut, logicalProcessors. Cumulative counters; the page diffs them client-side to derive per-second rates.

/diag/mbxhub returns a per-MBXHub instrumentation snapshot — counters specific to this plugin (request rates, broadcaster fan-out, lock waits, etc.) rather than the OS-level metrics in /diag/perf. The /diag page renders this as a second tile row. Same diagEndpointEnabled gate.

/diag/autoq/picks returns the last 20 AutoQ decision records, newest first — one per pick. Each names which entry point ran (fill, pick, generate, journey, preview, connect, station-play, send), what each eligibility gate removed, where the pick aimed and how far it reached, the top scorers with the components that produced them, what a quota cut, the ordering, and what reached the queue. Double-gated: needs diagEndpointEnabled and diagnostics.pickJournalEnabled. With the journal on, the same records are also appended one JSON object per line to autoq-picks.log beside mbxhub.log (5 MB, 2 archives), so a bug report carries them; the wire and the file use the same formatter and are byte-identical. Two shapes a reader must handle: a normally-numeric field is the string "NaN" / "Infinity" / "-Infinity" when non-finite, and on a send record sentUrls/sentQueued are the listener’s own tracks while queued is AutoQ’s fill — they are never combined into one number. A send record also carries sendMode (shown as mode= on the summary line): the steer variant that applied (refresh/reuse/restart), the same value the send’s response reports as mode, so the toast a listener saw and the journal line a triager reads cannot tell two different stories. sentUrls itself is capped at 50 entries so one huge multi-select cannot write an unbounded line; sentTotal carries the uncapped count of what was sent. A record with no poolRecorded never drew a pool at all — distinct from a draw that came back empty.

/diag/snapshot (v0.5.2.6+) takes a JSON body containing the page’s client-side ring (samples + derived rates + small header) and appends a formatted text block to diag-snapshots.log next to mbxhub.log. Each snapshot is delimited by “=” rules with a per-metric min/avg/max/latest table and the raw samples JSON below for forensic re-processing. Triggered by the Snapshot button on the /diag page; same diagEndpointEnabled gate. Response: { success, path, bytes, at }.

/diag/search (v0.5.3.0) returns a rolling p50/p90/p95/p99 summary over the last 256 search calls (in-memory ring, ~28 KB, server-wide singleton). Summary is segregated by endpoint: library (calls into /library/search), federated (calls into /search), and combined. Each block carries totalMs {p50,p90,p95,p99,max,mean}, candidates {p50,p95,max}, and mbCalls {p50,p95,max}. The recent array (default 50, override with ?recent=N, capped at ring capacity) lists the newest entries with per-stage timings (mb / cue / am / pf / sort / pg) and per-family MB-call counts (qf / ql / qlr / gt / gts / gp / gb / pl). POST /diag/search/reset clears the ring (operator-triggered flush; empty body, send Content-Length: 0). Same diagEndpointEnabled gate. Returns 403 FORBIDDEN when ApiReadOnlyMode is set — kiosk deployments can’t have their perf history wiped by remote clients.

// Enable in mbxhub.json:
{
  "diagnostics": {
    "diagEndpointEnabled": true
  }
}
// Then visit:
//   http://host:8080/diag         → live page
//   http://host:8080/diag/perf    → JSON snapshot

Returns API version information. Includes host field with the configured discovery name (or machine name if not set), and branch — the git line this build came from (master, release, a feature branch, or unknown outside a repo). The branch is deliberately absent from displayVersion for the lines we ship from: a bare version number IS the release, and a suffix marks something as not one. It is reported here instead, because a version string is identity and this endpoint is diagnostics — without it, answering “which line is this build on” means having the repo to hand and running git branch --contains. Also signature and signatureVerified: the running plugin is checked against the Halrad signing certificate (a valid signature AND our certificate, since either alone can be satisfied by a file that should not pass); signatureVerified is true only for a shipped, unaltered build. “Could not determine” is reported as its own state, never as verified. The Diag page shows the same.

Returns this node's capabilities for cross-channel SSDP discovery. Used by Shell and other MBXHub nodes to identify what this instance offers.

// Response:
{
  "node": "plugin",
  "version": "0.5.5.1",
  "capabilities": ["rest-api", "websocket", "player-control", "autoq", "discovery"],
  "endpoints": {
    "rest": "http://host:8080",
    "ws": "ws://host:8080/ws"
  }
}

Health check endpoint (alias: /system/ping). Returns status, service and apiVersion.

apiVersion is the extension contract's version, not the product's. It is a string, currently "1". Under a fixed value no field is removed from a response and no response type changes; fields may be added, so a client must tolerate members it does not know. A change to the contract bumps the value, and the bump is announced. The product version moves every release and is reported by GET /system/version — pin an integration against apiVersion, never against that. It is on /ping because /ping is the first response most integrators read, so the contract is known before anything else is.

// GET /ping
{
  "success": true,
  "data": {
    "status": "ok",
    "service": "MBXHub",
    "apiVersion": "1"
  }
}

Returns enabled feature flags: banlist, ratings, loved, reactions, streaming, playReporting (false when apiDisablePlayReporting or apiDisablePlayCountUpdates is on — clients watching this flag stop sending play reports under either), partymode, autoq, transcode (true only when transcode.enabled AND ffmpeg actually resolves — the capability statement clients key the ?compat=1 ask on), diag (v0.5.3.4 — mirrors diagnostics.diagEndpointEnabled). Clients use these to show/hide UI elements.

Also carries libraryTagsWritable — whether a library-tag write (POST /dashboard/love, POST /dashboard/rate/{n}) can actually succeed right now. This is a different question from ratings/loved, which say whether the feature exists at all: a hub can have ratings enabled and still refuse every write, which is the stock configuration (apiReadOnlyLibraryTags defaults true). Effective, like streaming beside it: false when any of apiReadOnlyMode / apiReadOnlyLibrary / apiReadOnlyLibraryTags is on, and false while a party is active (tag writes are refused for every role during a party, DJ included). Render the stars and heart either way — reading a rating always works; what this flag governs is whether to offer to change it. It is a snapshot, so treat the verb’s own 403 as the authority.

And tagEditNotice — whether a client may explain that refusal. Independent of libraryTagsWritable: that one says the write is refused, this one says whether to say so out loud. False when disableTagEditNotice is on, which exists for a hub deliberately run read-only, where the block is the intended behavior and being told about it is noise. When false, still retire the control and still carry the reason on hover — only the transient notice is suppressed, never the explanation itself. An older hub omits the field entirely; treat absent as true, because a needless toast is a smaller failure than a control that silently does nothing.

Also carries lanBase — the http://<ip>:<restPort> a device elsewhere on this network uses to reach this hub. The field is absent when nothing qualifies, because responses omit null properties — read a missing key exactly as you would read null — and nothing qualifies when either no adapter carries a usable address or allowRemoteConnections is off, in which case the hub refuses every LAN caller anyway and a URL here would name a door that is closed. A page opened at 127.0.0.1 must use this, not location.host, when it hands a URL to something that will fetch the URL itself — a Cast receiver resolves a loopback address to the receiver, not to the hub. The address is read from the live adapters each time the endpoint is called: the adapter must be up and must not be loopback or a tunnel, and its IPv4 must be in a private range and not APIPA (169.254.x.x) — which is why a VPN or a public address is never published. A default gateway only breaks ties between addresses that already qualify; it is not a requirement. A non-null value is not a promise of reachability — the URL ACL, the Windows Firewall and IP filtering can each still refuse a given peer.

Also carries shellBridge — { port, binding, seenUtc } when the MBXHub Shell has announced its overlay bridge this hub run, otherwise null. A page offering “open this as a desktop window” should use that port rather than assuming restPort + 1; null means fall back to the convention. binding is wildcard (the normal case: the bridge binds under the Shell port’s http://+: reservation) or loopback (a box with no such reservation); loopback-only is enforced per request either way. It is not a liveness claim — it says where the Shell said it was listening, so probe before drawing anything.

The Shell announcing where its overlay bridge listens: { "port": 8081, "binding": "loopback" }. An empty body clears the announcement, which is a clean Shell shutdown saying so. Read back through GET /system/features.

Local callers only (403 otherwise): this is one process on this machine telling another where it is, and a page that believed a remote announcement would send pop-out requests at a port somebody else chose. Held in memory, never persisted — a bridge that is not running should stop being advertised when the hub restarts, and the Shell re-announces on every start.

The machine audited against the configured setup mode: which URL reservations and firewall rule this mode needs, and which of them are actually there. mode is local, private or shared; each entry’s verdict is fine, wrong (needed and missing) or extra (present and not needed — what a hub left behind after moving down to This computer only). consistent is true when nothing the mode needs is missing; extra entries never break it. wrong and extra list entry names, and may also contain Firewall rule — the rule is audited alongside the entries but is not a row in entries[], so do not expect to find every name there.

Local callers only (403 LOCAL_ONLY otherwise), and read-only: it exposes nothing a local netsh http show urlacl does not, and repair stays a console act — MusicBee → MBXHub Settings → Network Status → Fix. This endpoint offers no write. 503 NOT_AVAILABLE when the audit is not wired in this host.

// GET /system/network-setup
{
  "success": true,
  "data": {
    "mode": "private",
    "entries": [
      { "url": "http://+:8080/", "name": "REST API", "needed": true, "present": true, "verdict": "fine" }
    ],
    "firewallRule": { "needed": true, "present": true, "firewallOn": true },
    "wrong": [],
    "extra": [],
    "consistent": true
  }
}

v0.5.3.4. Returns the friendly display-name MB has configured for each of the 48 tags exposed by browse.customSorts (Custom1..Custom16, Virtual1..Virtual25, Year, OriginalYear, SortAlbum, SortAlbumArtist, SortArtist, SortTitle, SortComposer). Server reads Setting_GetFieldName for each; only entries whose user-set name differs from the raw enum are returned. Used by settings.html's customSorts tag-picker to render AutoQ Moods (Custom1) instead of just Custom1.

// GET /system/custom-tag-names
{
  "success": true,
  "data": {
    "names": {
      "Custom1": "AutoQ Moods",
      "Custom2": "Mood Rating",
      "Virtual1": "Energy"
    }
  }
}

Get or update hub configuration (ports, enabled modules, log verbosity, library behavior). restPort and restEnabled changes require localhost (403 for remote). All changes blocked for remote clients during party mode.

Beyond the network fields (restPort, restEnabled, wsEnabled, defaultPage), GET and PUT also surface (MBRC was cut; mbrcPort / mbrcEnabled no longer exist):

{
  "logLevel": "Info",                              // trace/debug/info/warn/error, case-insensitive; propagates to Shell
  "library": { "disableStrictSearch": false }    // v0.5.2.4+: disables phrase-per-field strict search
}

GET additionally returns a read-only dashboardLayout block. Static pages have no other route to these values — the dashboard is server-rendered and reads settings directly, but browse.html and the injected command palette are plain assets, so this response is their config channel. Write these through PUT /system/config (or the settings page), not here:

{
  "dashboardLayout": {
    "disableVirtualTracklistBadge": false,       // read by browse.html for the CUE / SET LIST chip
    "commandPalette": {
      "enabled": true,                           // the ONLY off switch on play/explore/nowplaying/browse/hud,
                                                 //   which include the palette bootstrap unconditionally
      "openShortcut": "Ctrl+K",
      "recentLimit": 8,                          // clamped 1..50 client-side
      "bucketLimit": 100,                        // clamped 1..500 client-side
      "actions": []                              // empty = curated defaults
    }
  }
}

GET also returns a read-only hud block, for the same reason — browse.html has to know these before it sizes its album fetch. Write them through PUT /system/config or the settings page:

{
  "hud": {
    "recentAlbumViewLimit": 0,                   // albums shown when Browse is sorted by Recently Added
    "randomAlbumViewLimit": 0                    // albums shown when Browse is sorted by Random
  }
}

Both are 0 = unlimited, which is the shipped behavior. They cap only the two discovery sorts: A–Z, Album Artist and Year are lookup orders whose completeness the A–Z rail depends on, and are never capped. Random additionally bypasses the browse page's per-sort memoize cache so each visit is a fresh shuffle — at 25 albums the cached order would otherwise be the same 25 for the whole session.

Only fields a client actually reads are carried. commandPalette.showChip is deliberately absent because the chip is rendered server-side. Added v0.5.5.0 — before it, every palette knob above was declared, validated and read at the right name but never traveled, so changing one did nothing.

logLevel is validated against the same vocabulary as HubLogger.ParseLevel/ShellLog.ParseLevel; invalid values are silently ignored (same soft-skip pattern used for restPort range checks). library.disableStrictSearch takes a nested object — the parent object is created if missing. Neither requires localhost; both are UX-level settings safe to change remotely. Everything else in mbxhub.json, including search.live.minQueryLength and the dashboardLayout values above, is written through PUT /system/config and listed by GET /system/settings/schema; this endpoint carries a hand-picked subset and is not a general settings writer.

Returns schema for all configurable settings. Each entry includes:

Security: blocked when disableRemoteConfig is true (403) or during party mode (403). The /pages/settings.html page consumes this endpoint.

Update configurable settings via dotted key paths. Only properties decorated with [ConfigSetting] can be modified, and only those in a category the schema offers — the keys this route writes are exactly the keys GET /system/settings/schema lists.

Body: JSON object with dotted keys:

{"autoQ.batchSize": 10, "debugMode": true}

Console-only categories are refused. A key in Network, Features, Security or RateLimit is answered at the machine, in MBXHub's settings dialog in MusicBee, and this route replies 403 SETTING_CONSOLE_ONLY naming the offending keys — and applies nothing at all, so pairing a protected key with an ordinary one writes neither. A security control you can change over the network is not a security control.

Security: blocked by apiReadOnlyMode (403), disableRemoteConfig (403), and party mode (403). POST is an alias for PUT.

Get or set the default redirect page (body: {"defaultPage":"/pages/player.html"})

Security: PUT is blocked by disableRemoteConfig (403) for a caller that is not on the loopback interface.

Get the theme THIS caller renders with, or update the hub's own theme. GET answers the caller's resolved theme — its own values if the device carries a mbxh_device_theme cookie (see /device/theme), otherwise the hub's. ?scope=hub answers the hub's own values regardless of the caller's cookie. PUT always writes the hub.

Two configurable mode slots (mode1, mode2) each with 13 HSL fields: accentHue (0–360), accentSaturation (0–100), accentLightness (0–100), bgHue (0–360), bgSaturation (0–100), bgLightness (0–100), surfaceHue (0–360), surfaceSaturation (0–100), surfaceLightness (0–100), textHue (0–360), textSaturation (0–100), textLightness (0–100), intensity (0–100, saturation multiplier: 0 = grayscale, 100 = full color). Partial updates supported — only include the fields you want to change.

// GET response:
{
  "activeMode": 1,
  "mode1": {
    "accentHue": 197, "accentSaturation": 80, "accentLightness": 55,
    "bgHue": 203, "bgSaturation": 30, "bgLightness": 94,
    "surfaceHue": 203, "surfaceSaturation": 30, "surfaceLightness": 96,
    "textHue": 203, "textSaturation": 50, "textLightness": 13,
    "intensity": 100
  },
  "mode2": {
    "accentHue": 197, "accentSaturation": 80, "accentLightness": 55,
    "bgHue": 203, "bgSaturation": 30, "bgLightness": 7,
    "surfaceHue": 203, "surfaceSaturation": 30, "surfaceLightness": 10,
    "textHue": 203, "textSaturation": 50, "textLightness": 90,
    "intensity": 100
  },
  "active": {
    "accentHue": 197, "accentSaturation": 80, "accentLightness": 55,
    "bgHue": 203, "bgSaturation": 30, "bgLightness": 94,
    "surfaceHue": 203, "surfaceSaturation": 30, "surfaceLightness": 96,
    "textHue": 203, "textSaturation": 50, "textLightness": 13,
    "intensity": 100
  },
  "disablePinchZoomLock": false,
  "deviceOverride": false,   // true when these values came from this device's own cookie
  "canWriteHub": true        // whether a PUT /system/theme from this caller would be accepted
}

// PUT examples:
{"activeMode": 2}                                     // Switch to mode 2
{"mode1": {"accentHue": 180}}                         // Update just accent hue on mode 1
{"mode1": {"bgLightness": 10, "textLightness": 90}}     // Make mode 1 dark
{"mode1": {"intensity": 0}}                           // Desaturate mode 1 to grayscale

deviceOverride says whether the values returned are this device's own rather than the hub's; it is reported under ?scope=hub too, where the values are the hub's but the device's state is still what the caller needs to know. canWriteHub says whether a PUT /system/theme from this caller would be accepted, so an editor can show the right affordance instead of discovering a 403 on save.

PUT broadcasts a ThemeChanged WebSocket event and sets the mbxh_theme cookie for dashboard SSR.

Security: PUT is blocked by disableRemoteConfig (403) for a caller that is not on the loopback interface.

Set, or give up, THIS device's own theme. PUT takes the same body as PUT /system/theme and starts from the theme this caller currently renders with, so a body naming one field changes one field. DELETE is how a device goes back to following the hub.

The whole effect is a cookie on the caller — mbxh_device_theme, a year long, path /, SameSite=Lax. Nothing on the hub changes: no setting is written, no ThemeChanged event is broadcast, and other devices see nothing. disableRemoteConfig therefore does not apply — it guards the hub's settings, and this is not one, so a phone that could never change the hub's theme can change its own.

A device with no cookie follows the hub, and every page it is served is rendered with the hub's theme. DELETE expires the cookie rather than writing the hub's current values into it: a device holding a copy of today's hub theme looks right and has silently stopped tracking every later change.

Both answer the same payload as GET /system/theme — PUT with deviceOverride: true and the device's new values, DELETE with deviceOverride: false and the hub's.

The theme editor — the dashboard's theme drawer, behind the gear, and /pages/theme.html — carries an Apply to: This device | All devices choice. This device saves through PUT /device/theme, which disableRemoteConfig does not gate. All devices saves through PUT /system/theme, and where the hub will not accept that from this caller it is shown disabled with the reason. All devices includes THIS device: saving there from a device that had a theme of its own gives that theme up (the same DELETE /device/theme), so the screen shows what was just published and the device follows the hub again — otherwise it would publish a change it could not see. Follow the hub (DELETE /device/theme) is offered while the device has a theme of its own. A device with its own theme ignores the hub's ThemeChanged broadcast.

Not on the party surface: while a party is running, a remote guest's device cannot set a theme of its own.

// PUT examples (same body as PUT /system/theme):
{"activeMode": 2}                                     // This device uses mode 2
{"mode1": {"bgLightness": 10, "textLightness": 90}}     // Dark, on this device only

// Response header on PUT:
Set-Cookie: mbxh_device_theme=v1.2.0.197-80-55-...; Path=/; Max-Age=31536000; SameSite=Lax

// Response header on DELETE (the cookie is expired, not overwritten):
Set-Cookie: mbxh_device_theme=; Path=/; Max-Age=0; SameSite=Lax

Process metrics for the MusicBee host process. Used by MBXHVAL for remote monitoring.

// Response:
{
  "success": true,
  "data": {
    "process": {
      "name": "MusicBee",
      "cpuPercent": 2.15,
      "memoryMB": 185.3,
      "privateMemoryMB": 210.5,
      "threadCount": 42,
      "handleCount": 1250
    },
    "gc": {
      "gen0": 150,
      "gen1": 30,
      "gen2": 5,
      "totalMemoryMB": 45.2
    },
    "timestamp": "2026-03-10T12:00:00.0000000Z"
  }
}

Server start time and uptime. Used by dashboard to detect restarts.

// Response:
{
  "success": true,
  "data": {
    "startedAt": "2026-03-10T20:30:00.0000000Z",
    "uptimeSeconds": 3600,
    "uptime": "1h 0m"
  }
}

Generate QR code PNG image for the MBXHub base URL. Optional ?url= for custom target.

Open the plugin's Settings dialog on MusicBee's UI thread — used by the first-run setup screen's Settings link. Local, or a paired Shell: a remote caller must carry a valid X-MBXHub-SAC signature (see Signed calls from a paired Shell under Charms & Capabilities). With no signature at all: on a paired hub 403 SAC_REQUIRED, and on a hub that has never paired the unchanged 403 FORBIDDEN. With a signature that does not hold up — including on a hub with no secret to check it against — 403 SAC_INVALID. 404 when disabled via disableOpenSettings — the kill switch outranks a caller that authenticated — and 503 when the plugin UI isn't available. The dialog opens on the hub's screen, which on a headless jukebox is a screen nobody is standing at.

Redeem a pairing code for the Secure Access Channel secret — the exchange that makes a Shell a paired Shell. Body {"token":"ABCDE-FGHIJ"}, in the body and never a query string. Answers {"secret":"<base64url>","hubId":"<hub id>"}; the Shell keys its copy of the secret by that hubId, so both fields are needed. Closed unless a window is armed at the hub's console. A person clicks Pair a Shell in the MBXHub settings dialog on the hub's own machine; that click is the only thing that opens this endpoint, and there is no way to arm one remotely. The window lasts five minutes, is good for one redemption, and closes after five wrong codes. Refusals: 403 SAC_PAIRING_CLOSED when no window is open (the state of every install nearly all of the time), 403 SAC_PAIRING_REFUSED for a wrong code or a spent budget, 500 SAC_PAIRING_UNAVAILABLE when the hub has nowhere per-user to keep a secret — that last one leaves the window open, because nothing was handed out. The code is Crockford base32 and is read forgivingly: the hyphen is optional, case does not matter, and O/0 and I/l/1 are the same character. The 32-byte secret crosses the network once, in this one response, in the clear — there is no TLS, and a five-minute window a person opened by hand with somebody watching is what bounds that. Every attempt is logged with the caller's address; the code and the secret are not. When no window is armed, the optional REST password stands in front of this route like any other non-local call. One secret per hub. Pairing replaces any previous pairing — a Shell paired earlier will need to be paired again (a Shell on the hub's own machine is re-paired automatically).

Returns the client's IP address as seen by the server. Used by the SMTC Link Charm to discover the client's local Shell when accessing a remote dashboard.

Other MBXHub instances on the LAN, as discovered by the Shell's SSDP scan. The plugin reads the shared file %LOCALAPPDATA%\MBXHub\hub-neighbors.json (written by the Shell) and returns its contents; shared.js calls this on every page load and merges the result into the browser list that /pages/hubs.html renders. Returns an empty array when the file is missing — Shell not running, nothing discovered yet, or a different user profile. Never errors: hub-neighbors is a hint, not a contract.

The canonical list of registered sorts (built-ins plus customs), so callers don't have to guess sort ids. Direction is request-side only — never a property of an entry; directionApplies says whether asc/desc is meaningful for that sort at all. Returns {sorts: []} rather than an error when the registry isn't wired.

// Response:
{
  "success": true,
  "data": {
    "sorts": [
      { "id": "album", "label": "Album", "kind": "builtin",
        "directionApplies": true, "valueKind": "text" }
    ]
  }
}

Diagnostic probe over the sort index: returns the first 20 album names in the requested order. Exists to smoke-test sort wiring on its own, without going through a /library/* endpoint. sort is required. dir defaults to asc.

Errors: 400 MISSING_SORT (no sort parameter), 400 UNKNOWN_SORT (id doesn't resolve against /system/sort-registry), 503 SORT_INDEX_UNAVAILABLE (index not wired).

Push a named event into the WebSocket broadcaster from sub-process components (Shell, scripts, automations). It goes out as the SystemEvent type, carrying {name, payload} — the pushed name and the request body — so a client subscribes to SystemEvent, never to the pushed name: only the types in EventTypes.All can be subscribed to, and a client with no subscriptions receives it either way. A body that is empty or not JSON leaves payload null and the event still goes out. Used to fan out signals that originate outside the plugin process.

Force re-extract all embedded resources (pages and charms) to disk. Overwrites existing files.

// Response:
{
  "success": true,
  "data": {
    "pagesUpdated": 8,
    "charmsUpdated": 3,
    "userModified": []
  }
}

Accepts browser-side log events and writes them to mbxhub.log. Use this instead of console.log for operational telemetry from dashboard pages so problems in guest browsers land in the server-side log where the operator can see them. Accepts either a single event or a batch via events[]. Silent on empty body (returns {success:true, data:{accepted:0}}); accepted counts events that passed validation and reached the log. Invalid JSON returns 400 INVALID_REQUEST (not INVALID_JSON — this endpoint predates the topology handler’s specific code). Access: ActionCategory.System — admin-gated. PartyMode guests are rejected (they lack System) so guest-sourced log entries can’t mix into operator telemetry.

// Single event:
POST /system/client-log
{ "level": "warn", "msg": "Retry #3 on /queue/add" }

// With page context (prefixes the log line as "[page] msg"):
POST /system/client-log
{ "level": "info", "msg": "Charm bar rendered", "page": "dashboard" }

// Batch:
POST /system/client-log
{ "events": [
  { "level": "info",  "msg": "Charm bar rendered" },
  { "level": "error", "msg": "ThemeChanged handler threw" }
] }

// Response:
{ "success": true, "data": { "accepted": 2 } }

Recognized fields: msg (required; empty or missing drops the event), level (optional, defaults to info; free-form string mapped to server log levels, unknown values log as info), and page (optional; wraps the output as [page] msg). Any other fields on the event object are silently dropped — if you need to capture a stack trace or structured data, concatenate it into msg. Both msg and page are sanitized: CR/LF/NUL stripped (blocks log-line forgery) and length-capped (4096 chars for msg, 256 for page).

Report a client-side (Listen Here) playback exit. The server applies MusicBee's own play-count thresholds (PlayCountTriggerPercent / PlayCountTriggerSeconds) to decide played vs skipped, then updates play statistics — so browser-streamed plays count exactly like speaker plays. For CUE virtual sub-tracks, send the raw file position plus cueStartMs; the listened window is measured against durationMs (the sub-track duration).

POST /player/report-play
{ "url": "C:\\Music\\track.mp3", "positionMs": 185000, "durationMs": 240000, "cueStartMs": 0 }

// Response:
{ "success": true, "data": { "url": "...", "counted": true, "countType": "IncreasePlayCount",
    "playedPercent": 77.1, "playedSeconds": 185, "result": true } }

countType is IncreasePlayCount (past threshold), IncreaseSkipCount (exited early), or NoChange (position 0 — nothing recorded). Optional abandoned: true marks a non-deliberate exit (tab close, output toggle, external track change): past threshold it still counts a play, below it nothing is recorded — never a fabricated skip. Optional cue: true marks a CUE-backed source — required for a sheet's FIRST sub-track, whose cueStartMs is 0. When durationMs is omitted or 0, the server derives it from the CUE sheet for sub-tracks (next track start − this start; the sheet's last track has no derivable end, so only the seconds rule can count it as a play and no skip is ever fabricated) or the library's duration for whole files, so the percent threshold still applies. Counted plays also feed the AutoQ session signal and, when TrueShuffle is enabled, the shuffle played-set and AutoReset completion check — neither feature is required for counting. Duplicate reports from the same client for the same track (keyed url + cueStartMs, so CUE sub-tracks never collide) are absorbed within an adaptive window (deduped: true), and play-statistic updates share a per-IP rate limit (rateLimitPlayStatsPerMinute, 429 when exceeded; loopback exempt). Optional disableScrobble: true suppresses Last.fm scrobbling for this report. 404 if the file is not in the library or apiDisablePlayReporting/apiDisablePlayCountUpdates is enabled.

Returns current track info with full metadata

// Response:
{
  "success": true,
  "data": {
    "playing": true,
    "url": "file:///C:/Music/Artist/Album/track.mp3",
    "title": "Love Don't Live Here",
    "artist": "Breaking Rust",
    "album": "Greatest Hits",
    "albumArtist": "Breaking Rust",
    "year": "2024",
    "genre": "Rock",
    "trackNo": "3",
    "discNo": "1",
    "rating": "4.5",
    "love": true,
    "duration": 234000,
    "position": 45000
  }
}

Returns the now playing list. Supports ?offset=0&limit=50. MusicBee keeps ONE now-playing list and shows two views of it: Playing Tracks (every row) and Up Next (what will actually play, in play order). Removing a track from Up Next leaves its row in the list and does not mark it played, so the raw list contains rows that will never play. Each track therefore carries upcoming — true when MusicBee's own play order still includes it. Render Up Next by keeping upcoming: true rows; upcomingTotal is the count of those across the WHOLE list, which is not derivable from total - currentIndex - 1 (that counts removed rows) nor from a filtered page. Each track carries an optional provenance object — who filled it and why (driver: AutoQ | TrueShuffle | Journey | Station | Manual, a short reason, and whenUtc). Omitted for tracks with no stamp (older fills or direct MusicBee queue adds).

// Response:
{
  "success": true,
  "data": {
    "currentIndex": 5,
    "total": 150,
    "upcomingTotal": 142,
    "offset": 0,
    "limit": 50,
    "tracks": [
      {
        "index": 0,
        "url": "file:///C:/Music/track1.mp3",
        "title": "First Track",
        "artist": "Artist Name",
        "album": "Album Name",
        "duration": 234000,
        "upcoming": true,
        "provenance": {
          "driver": "AutoQ",
          "reason": "mood:Energetic magnet",
          "whenUtc": "2026-07-26T12:00:00.0000000Z"
        }
      },
      // ... more tracks (provenance omitted when unknown)
    ]
  }
}

Query library with ?query=, ?artist=, ?albumArtist=, ?album=, ?genre=, ?people=, ?sort=, ?include=, ?roles=.

v0.5.3.4 — ?people= on album expansion. When ?album=Y&people=X is set the post-filter probes MB's full role-union per track — Artists (144 — Artist + Performer + Guest + Remixer), Composer (43), and Conductor (45) — rather than relying on the ArtistPeople XmlFilter alone. The XmlFilter omits the GuestArtist role bucket, so a track tagged with the queried person as guest (e.g. David Guetta — The Whisperer (feat. Sia)) was previously dropped from expansion even though the album-by-artist count showed it. Whole-library ?people= (no ?album=) still uses the fast ArtistPeople XmlFilter path; pure-guest credits won't surface there but are reachable by drilling into the specific album.

v0.5.3.4 — ?include=<TagName>. Each returned track row carries extraField + extraValue with the per-track value of the requested tag. Accepts any tag from the 48-tag customSorts allowlist: Custom1..Custom16, Virtual1..Virtual25, Year, OriginalYear, SortAlbum, SortAlbumArtist, SortArtist, SortTitle, SortComposer. Unknown values are silently ignored. Used by browse.html to surface the active custom sort's per-track value when expanding an album under a custom-* sort.

v0.5.3.4 — ?roles=true. Adds every per-track role-credit field MB tracks separately: artistsRole (145), performers (146), guests (147), remixers (148), composers (43), conductors (45), artistsUnion (144 — the full role-union). Raw strings preserved (mixed separators across tag implementations). Default off so regular dashboard queries don't pay for the extra Library_GetFileTag reads; only paid for when explicitly requested.

// GET /library/files?artist=Breaking%20Rust&limit=10
{
  "success": true,
  "data": {
    "total": 42,
    "offset": 0,
    "limit": 10,
    "tracks": [
      {
        "url": "file:///C:/Music/Breaking Rust/track.mp3",
        "title": "Love Don't Live Here",
        "artist": "Breaking Rust",
        "album": "Greatest Hits",
        "duration": 234000
      },
      // ... more tracks
    ]
  }
}

Full-text search: ?q=search+term&sort=alpha (searches title, artist, album, genre; diacritic and punctuation normalized so "cafe" matches "Café" and "acdc" matches "AC/DC"). Two matching modes:

• strict (default) — the typed phrase must appear as a contiguous run of whole words in a single field (title, artist, album, or genre). "st anger" matches the album "St. Anger" (normalizes to the same phrase) but NOT "Stranger", "Strange Anger", or a track whose title contains "Anger" while its album contains "Story."
• substring — loose matching, any query word appearing anywhere as a substring passes. "anger" matches "Stranger."

The default mode is controlled by the Library.DisableStrictSearch setting (false by default = strict). Override per-call with ?substring=true|false. The response payload includes a mode field echoing which mode was used.

v0.5.3.0: DSL auto-detection is on by default (library.search.dsl.enabled = true). Qualifier syntax (artist:, album:, genre:, year:, rating:, fmt:, range / boolean / grouping operators) routes through SearchDslParser automatically when detected; plain free-text queries take the strict/substring path as before. Force per-call with ?dsl=true; set library.search.dsl.enabled = false to require the explicit opt-in. Cheat sheet at GET /library/search/syntax.

Unreleased — any-field search. The DSL field registry now covers every MusicBee custom slot: custom1:…custom20: translate to a Field="CustomN" condition (e.g. custom7:live; Custom17–20 arrived with MusicBee 3.5). Combine with existing qualifiers as usual (albumartist:"various" custom7:live). Mood-position filtering uses the first-class arousal:/valence: range qualifiers (0–1, e.g. arousal:>0.7) — see the qualifier table above.

v0.5.3.0 backstop: queries shorter than search.live.minQueryLength (default 2) return 400 QUERY_TOO_SHORT with body { "error": "Query must be at least N characters (got M)." }. Single-char walks visit every track on a 200k library (~4 s) and stall every other MB-API consumer for the duration of the cursor lock; the backstop protects fleet-wide responsiveness from runaway non-conforming clients (curl, scripts). Set search.live.minQueryLength = 0 to disable.

v0.5.3.0. Returns the DSL grammar as JSON (qualifiers, operators, worked examples). Authoritative source — the reference below is rendered from the same data shape. Used by Cmd+K's cheatsheet and any other client surfacing DSL syntax to users.

Response shape: { version, qualifiers: [{ name, type, allowsRange, allowsOperators, filterable, mapping, enumValues }], operators: [{ symbol, description }], examples: [{ query, description }] }. filterable (bool) marks the qualifiers the AutoQ candidate filter can evaluate — a filter-scoped client derives its allow-list from this flag rather than hardcoding one.

Query DSL Reference

The DSL layers on top of free-text search: every plain word still matches normally, qualifiers narrow the result, operators compose. Auto-detected on /library/search and /search when library.search.dsl.enabled = true (default); force per-call with ?dsl=true.

Qualifiers

Operators

Examples

Notes

• Default composition is AND between terms. Use OR (or lowercase or) for disjunction; parentheses for grouping.
• Where a grouped query runs. A query that is only a group — genre:rock OR genre:metal — runs entirely in MusicBee's own engine. Put a group beside another condition — artist:davis (genre:rock OR genre:jazz) — and the group is evaluated here instead, because MusicBee silently drops the sibling condition when a group sits next to it (measured 2026-08-18: artist:davis matched nothing on its own, yet the combined query returned 3385 tracks). The results are the same either way; the difference is that the second shape is capped, and a query producing more candidates than library.search.dsl.maxPostFilterCandidates answers 413 POST_FILTER_CAP_EXCEEDED rather than quietly returning the wrong set. Add a selective condition, or write the group on its own.
• Free-text terms still work alongside qualifiers — radiohead year:>=2000 filters Radiohead tracks from 2000 onward.
• Post-filter qualifiers (mood, playlist, lyric) run after the candidate set is fetched, so they're capped by library.search.dsl.maxPostFilterCandidates (default 5000).
• Unknown qualifiers return 422 INVALID_DSL with a parse position and Levenshtein-based “did you mean” suggestions.
• Date format: ISO (2025-01-01), relative (now-7d, now-30d), or named alias from library.search.dsl.dateAliases (defaults: lastweek, lastmonth, thisyear).
• DSL result rows carry dateAdded and dateAddedSort — the raw MusicBee DateAdded string (the same value GET /library/file/{url} returns) and the same moment as yyyy-MM-ddTHH:mm:ss, or "" when it could not be read — so a client can order query-backed rows newest-first without a second call per track, and without running Date.parse over a locale string it cannot interpret the same way in every browser. On /library/search?dsl=true only; the non-DSL search rows and /library/files keep the shape they have.

v0.5.3.0 federated search. Runs typed buckets (tracks / albums / artists / playlists / saved) in parallel and returns a unified response with cursor pagination on the tracks bucket, facet counts, and a top-hit. Backs the Cmd+K palette and (v0.5.3.0+) the dashboard search bar, player.html, browse.html, and explore.html.

DSL routing (v0.5.3.0 post-launch): /search auto-detects DSL queries the same way /library/search does — qualifier colons (year:, rating:, etc.), .. ranges, >/< comparisons, OR , leading - exclusion. When detected and Search.Dsl.Enabled=true (default), the query routes through the DSL pipeline and the response carries mode: "dsl". Per-call ?dsl=true still works as an explicit opt-in. Plain free-text queries continue to use strict/substring mode as before. Tracks bucket is sorted by match-strength score (title > album > artist, with prefix-match bonus) so the most-relevant result appears first regardless of mode.

Params: ?q=&buckets=tracks,albums,artists,playlists,saved&limit=N&cursor=opaque. Cursors are opaque and TTL-checked; stale → 410, malformed → 400, query-mismatch → 400. Opaque is not signed — the payload is base64url JSON any caller can read and mint, and nothing checks that it came from here. That is deliberate: the cursor is advisory, ?offset= reaches exactly the same rows, and pagination is not an access boundary. Treat a cursor as a position, never as a permission. Same QUERY_TOO_SHORT backstop as /library/search. v0.5.3.0: per-bucket ?limit= hard cap raised from 200 to 500 (browse.html aggregates client-side over the tracks bucket and needs the headroom).

v0.5.3.0. Live engine + index state snapshot. Currently reports engine: "mb" (FTS5 substrate dropped during the post-decouple harvest; seam preserved for future engines).

One row per value of a field, largest first — the view behind /pages/slices.html. Params: ?by=genre|year|decade|rating|mood (required; anything else is 400 BAD_FIELD), &top= how many values get a preview row (defaults to slices.topN, clamped to 1–200), &preview= covers per row (defaults to slices.rowLength, clamped to 0–200, where 0 means every album in the value). top and preview come back clamped, not as they were sent. total is the number of distinct values, i.e. values.length + more.length; everything past top lands in more as name+count for the page’s More… list. Each preview row is exactly a /library/albums/detailed row, so artwork and verbs are the existing ones. Computed over the in-memory album index.

Which row an album lands in. genre: every genre tagged on the album, so a multi-genre album is in several rows — and an album with no genre is in no row, because genre has no missing bucket. year: the first four digits of the album’s Year tag, or "Unknown". decade: that year floored to ten and suffixed, e.g. "1990s", or "Unknown". rating: the album-rating tag when it is set, otherwise the mean of the album’s rated tracks rounded half-up, otherwise "Unrated". mood: the mood channel most of the album’s analyzed tracks fall in (ties break by channel name), or "No mood data" when none is analyzed. Values sort by album count descending, then by name; the missing bucket ("Unknown" / "Unrated" / "No mood data") always sorts last. Preview albums are newest-added first, then by name.

by=mood is the one expensive field — one channel lookup per track — so the per-album tally is cached and thrown away when the album index publishes a new snapshot. A mood source that throws answers 500 rather than reporting the whole library as having no mood data.

// GET /library/slices?by=genre&top=2&preview=1
{
  "success": true,
  "data": {
    "by": "genre",
    "total": 87,
    "top": 2,
    "preview": 1,
    "values": [
      {
        "value": "Rock",
        "albums": 412,
        "preview": [
          {
            "name": "The Dark Side of the Moon",
            "count": 10,
            "firstTrackUrl": "C:\\Music\\Pink Floyd\\Dark Side\\01.flac",
            "year": "1973",
            "dateAdded": "12/15/2025 2:32 PM",
            "dateAddedSort": "2025-12-15T14:32:00",
            "albumArtist": "Pink Floyd",
            "sortAlbumArtist": "Pink Floyd",
            "virtualKind": null
          }
        ]
      },
      { "value": "Jazz", "albums": 188, "preview": [ /* ... */ ] }
    ],
    "more": [
      { "value": "Ska", "albums": 7 }
    ]
  }
}

Evaluate a MusicBee expression: ?expression=<Artist> - <Title>&fileUrl=C:\Music\track.mp3. If fileUrl is omitted, evaluates against the currently playing track. Returns {expression, fileUrl, result}. Supports MusicBee template syntax (<Artist>, $If(), virtual tags).

MusicBee’s built-in placeholder image for tracks with no artwork. Returns binary image data with appropriate content type. Cache-Control: 24h.

Albums for an artist with year, track count, firstTrackUrl for artwork, and virtualKind ("cue" | "setlist" | null). Params: ?albumArtist= or ?artist= (one required), ?sort=alpha|year|year-asc. ?artist= queries ArtistPeople (broader match), ?albumArtist= queries AlbumArtist (exact album credit).

// GET /library/albums/by-artist?albumArtist=Pink%20Floyd&sort=year
{
  "success": true,
  "data": {
    "albumArtist": "Pink Floyd",
    "total": 3,
    "sort": "year",
    "albums": [
      {
        "name": "The Dark Side of the Moon",
        "year": "1973",
        "count": 10,
        "firstTrackUrl": "file:///C:/Music/Artist/Album/track.mp3"
      }
    ]
  }
}

List radio stations from MusicBee’s Radio node.

// Response:
{
  "success": true,
  "data": {
    "total": 5,
    "stations": [
      {"url": "http://stream.example.com/radio", "name": "Jazz FM"},
      // ...
    ]
  }
}

List podcast subscriptions. Query: ?query=

Flat episode listing. Query: ?id= (feed URL). Use this when the subscription ID is a URL rather than a simple ID.

Overview bundle of the most common settings in one response.

// Response:
{
  "success": true,
  "data": {
    "storagePath": "C:\\Users\\...\\MusicBee",
    "skin": "Default",
    "windowBordersSkinned": false,
    "lastFmUserId": "scott365",
    "webProxy": null
  }
}

Gracefully close MusicBee. Requires allowRemoteExit=true in settings for remote callers; localhost (request.IsLocal) is exempt when the request carries the X-MBXHub-Local header (any non-empty value — a caller-id requirement, not a secret: it identifies deliberate local callers, keeps browser pages from firing this cross-origin (no CORS preflight is granted for it), and is the hook for future per-caller allow/deny lists). A local call without the header follows the remote rules (allowRemoteExit). The Disable Features App Restart toggle blocks this endpoint entirely, even from localhost. A paired Shell's valid X-MBXHub-SAC signature stands in for the X-MBXHub-Local header and for nothing else: a remote caller still needs allowRemoteExit, and a signature that is presented and does not hold up — including on a hub holding no secret to check it against — answers 403 SAC_INVALID rather than falling through to the rules above.

Optional body to schedule a restart via Windows Task Scheduler before closing:

// Request (optional):
{
  "restart": true,   // schedule restart before closing (default: false)
  "delay": 22        // seconds to wait before restarting (default: 22, range: 1-300)
}

// Response:
{
  "success": true,
  "data": {
    "message": "MusicBee restarting in 10s",
    "restart": true,
    "delay": 22
  }
}

Restart MusicBee. Convenience alias for /app/exit with restart=true. Requires allowRemoteExit=true for remote callers; localhost (request.IsLocal) is exempt when the request carries the X-MBXHub-Local header (any non-empty value — a caller-id requirement, e.g. curl -X POST -H "X-MBXHub-Local: 1" http://localhost:8080/app/restart). A local call without the header follows the remote rules (allowRemoteExit). The Disable Features App Restart toggle blocks this endpoint entirely, even from localhost. A paired Shell's valid X-MBXHub-SAC signature stands in for the X-MBXHub-Local header and for nothing else: a remote caller still needs allowRemoteExit, and a signature that is presented and does not hold up — including on a hub holding no secret to check it against — answers 403 SAC_INVALID.

// Request (optional):
{
  "delay": 22   // seconds to wait before restarting (default: 22, range: 1-300)
}

Get shuffle cycle status

// Response:
{
  "success": true,
  "data": {
    "enabled": true,
    "totalTracks": 1000,
    "playedCount": 250,
    "remainingCount": 750,
    "percentComplete": 25.0,
    "cycleStarted": "2024-01-01T00:00:00Z"
  }
}

Get list of banned tracks. Query: ?offset=&limit=

// Response:
{
  "success": true,
  "data": {
    "total": 5,
    "offset": 0,
    "limit": 50,
    "tracks": [
      {
        "url": "file:///C:/Music/corrupted.mp3",
        "reason": "Audio corruption detected at 2:30",
        "bannedAt": "2024-01-01T12:00:00Z"
      }
    ]
  }
}

Get list of all influences. Query: ?offset=&limit=

// Response:
{
  "success": true,
  "data": {
    "total": 2,
    "offset": 0,
    "limit": 50,
    "influences": [
      {
        "type": "--",
        "target": "Genre",
        "value": "Audiobook",
        "timestamp": "2024-01-15T10:30:00Z"
      },
      {
        "type": "++",
        "target": "Artist",
        "value": "The Beatles",
        "timestamp": "2024-01-15T10:35:00Z"
      }
    ]
  }
}

Get current track's genre/artist and any matching influences (for UI state).

// Response:
{
  "success": true,
  "data": {
    "genre": "Rock",
    "artist": "Pink Floyd",
    "genreInfluence": null,
    "artistInfluence": "++"
  }
}

Check if ARiA input simulation is enabled

Quick wake: move mouse + send Shift key to wake sleeping/locked PC

Trigger a MusicBee library scan (built-in, like Wake PC). Sends Insert to open the scan-folders dialog, then a focus-skipped Enter to confirm it. Assumes Insert is bound to scan-folders (MusicBee default).

Send keyboard input. Body: {"keys": "^a"} (Ctrl+A). Optional: {"keys": "%{F4}", "window": "Notepad"} to focus window first. Prefix keys with ! to send to the current foreground window without refocusing MusicBee.

SendKeys format: ^=Ctrl, %=Alt, +=Shift. Special keys: {ENTER}, {TAB}, {ESC}, {F1}-{F12}, {UP}, {DOWN}, etc.

DuckyScript format: CTRL ALT V, SHIFT F1, ALT TAB. Modifiers: CTRL, ALT, SHIFT. Special: WIN/GUI (opens Start Menu, standalone only - not a modifier).

Focus a window by title. Body: {"window": "Notepad"} (partial match, case-insensitive)

Check RemoteApp status. Always accessible.

Response:

{
  "configured": false,
  "supported": true,
  "rdpEnabled": true,
  "edition": "Professional",
  "enabled": false,
  "apiDisabled": false,
  "message": "RemoteApp not configured. Run 'MBXHub.exe remoteapp setup' to configure."
}

Download a .rdp file for connecting to MusicBee as a RemoteApp. Blocked when remoteAppApiDisabled is true.

Query parameters:

• hostname - Override the hostname in the .rdp file (defaults to request Host header)
• Any other query parameter is forwarded as an .rdp setting override (e.g. audioqualitymode=0, redirectprinters=1)

Response: application/x-rdp file download (MusicBee.rdp)

403 when remoteAppApiDisabled is true.

Visibility: Dashboard footer link requires remoteAppEnabled and remoteAppApiDisabled: false. Footer links are configurable via dashboardFooterLinks in settings.

App program: On Windows Client (Pro/Enterprise), the .rdp file uses the full executable path from the registry. On Windows Server, it uses the ||AppName alias for RDS published app lookup.

Forward an HTTP or HTTPS request to a LAN device. Only private IPs are allowed (RFC 1918).

Request body:

{
  "method": "GET",
  "url": "http://192.168.10.100/ipcontrol/v1/systems/current/sources",
  "body": {}
}

• method — HTTP method to use: GET, POST, or PUT
• url — Full URL of the target device endpoint. Scheme must be http or https, and the host must be a private IP address.
• body — Optional JSON body to forward with POST/PUT requests.

HTTPS targets: some LAN gear only exposes its control API over HTTPS with a self-signed certificate — WiiM streamers serve httpapi.asp on port 443 that way. Those targets work: https://192.168.10.100/httpapi.asp?command=getPlayerStatus is forwarded like any other. The certificate is not validated for proxied requests — not the chain, not the hostname, not the expiry. The connection is encrypted but unauthenticated, so anything on the LAN path could impersonate the device. That is a deliberate trade: without it, self-signed devices are simply unreachable. The relaxation applies to the proxied request only — every other outbound connection MusicBee and MBXHub make still validates certificates normally.

Response: The target device’s response is passed through verbatim (status code and body).

Errors:

• 400 — Missing or invalid request body, missing method/url fields
• 403 — Target URL is not a private IP (public internet proxying is blocked), targets MBXHub itself, or uses a scheme other than http/https
• 405 — Only POST is accepted on this endpoint
• 502 — Target device unreachable or returned an error

Stream an audio or video file. The path must be URL-encoded and must be a file in the MusicBee library.

Path parameter: URL-encoded absolute file path (e.g. /stream/C%3A%5CMusic%5Csong.mp3).

Range support: Send Range: bytes=N-M header for partial content (required for seeking). The server responds with 206 Partial Content and Content-Range header.

Supported formats: mp3, flac, m4a, mp4, ogg, oga, wav, opus, aac, wma, aiff, aif. Actual browser playback depends on codec support — FLAC works in Firefox/Chrome/Edge, WMA is not supported by any browser. The play page’s Listen Here mode probes canPlayType, and for a format the browser reports it cannot decode it asks for the converted stream below rather than refusing outright; when no conversion is available it names the format on the output chip.

Query parameter — ?compat=1: a statement that the caller cannot play the original, not a request for a particular format — the server chooses what to convert to. When format conversion is enabled and ffmpeg is available, the file is converted and the result served with Content-Length and range support, so seeking and CUE offsets still work; the conversion is cached, so a file converts once. Otherwise the request is refused and the caller falls back to reporting the format unplayable. Without the parameter, behavior is unchanged. Requires ffmpeg — see docs/ffmpeg-and-transcoding.md.

DELETE /system/transcode-cache: drops every cached conversion and returns { cleared: <count> }. The cache is derived data that rebuilds on demand, so this is a rebuild trigger rather than destruction — your library files are never involved. Two uses: evicting a conversion you suspect, which previously meant finding the directory by hand; and forcing a cold conversion so a test actually exercises ffmpeg, since a conversion check passes against a warm cache even with ffmpeg uninstalled. Answers 200 even when conversion is switched off — the cache can still hold files from when it was on, and refusing to tidy up because the feature is off would be perverse. A file being streamed right now is left alone and counted as not removed, rather than failing the sweep.

One page holds the audio — POST /listen-here/claim and GET /listen-here/holder: every page that can play audio in the browser has its own audio element, and two pages in two browsers cannot see each other. Without a referee, one page takes the music, a second takes it again, and you are left with sound from a page you are not looking at while the controls in front of you reach a different one. The hub is the referee. A page that takes the audio posts { "holder": "<id>", "page": "<path>" } — holder is an id the page makes up for itself, 1–64 characters of letters, digits, dash or underscore (anything else is 400 INVALID_HOLDER, because the id is echoed to every client). The answer is { holder, page, changed, previous }. When the holder changes, the hub broadcasts the ListenHereClaimed WebSocket event and every other page holding the audio lets go: it stops its stream and returns to speaker output without resuming or seeking MusicBee, which the new holder has just taken over. A page re-claiming what it already holds is not a change and broadcasts nothing, so claiming on every track is free. GET /listen-here/holder answers { holder, page, since, url, positionMs, playing, ageMs } (all absent when nobody has claimed) for a page that may have missed the event — a suspended mobile socket, or the HUD, which has no socket at all and asks every few seconds while it holds the audio. The holder is kept in memory only: a hub restart forgets it and nothing breaks. All three routes change nothing in MusicBee and write nothing to disk, so they are classified with the reads, the same as /stream — whoever may play audio here may say that they are.

The hand-off — where the other page had got to: a claim may also say where the claiming page is, by adding "url" (the library path it is streaming), "positionMs" (file-absolute milliseconds) and "playing". When the holder changes and another page had the audio, the answer’s previous is { holder, page, url, positionMs, playing, ageMs }: where that page was, captured under the same lock that replaced it, so the page taking over can pick the track up there in the one round trip it already makes — instead of restarting it, or asking a room that has been sitting paused the whole time. ageMs is how old that report was when the claim was served; add it to positionMs if playing. Act on it promptly or not at all: an answer that arrives seconds late describes the moment of the press, and seeking a listener who has been playing since then is a jump, not a correction (the built-in pages ignore it after 2.5 s). A report needs both a url and a usable positionMs — a finite number, 0 or more. One without the other is dropped whole: it is never stored as 0:00, which would restart the track for the next page to take over, and it is never a reason to refuse the claim.

The check-in — POST /listen-here/progress: the holder says “I am here” with { "holder": "<id>", "url": "<library path>", "positionMs": 61000, "playing": true } and is answered { accepted, holder, page }. It is recorded only when the caller still holds the audio, and it can never take it: a page with no socket learns it lost the audio a few seconds late, and a check-in that could claim would steal the audio straight back from whoever just took it. A caller that is not the holder is told who is, so this doubles as the holder check — a page that is sounding sends it every few seconds in place of GET /listen-here/holder. accepted: false alone does not mean the audio was lost (a report with no usable position is not recorded either): let go only when holder names someone else.

Security:

• Path traversal (..) is blocked
• Only whitelisted audio extensions are served
• File must exist in the MusicBee library (verified via API)

Errors:

• 400 — Invalid path or non-audio extension
• 403 — File not in MusicBee library
• 404 — File not found or streaming disabled
• 416 — Range not satisfiable

Returns timer config: {intervalSeconds, shuffle}

List subfolder names under imageRoot. Files directly in root appear as _root.

List subfolder names under videoRoot. Files directly in root appear as _root.

List filenames in category. Returns {name, files:[], count}. Filenames only, no paths.

List video filenames in category.

Serve the next image (rotation state per category, sequential or shuffled). Returns image binary.

Serve the next video with HTTP Range support for seeking.

Serve a specific image by filename.

Serve a specific video by filename. Supports HTTP Range requests (206 Partial Content) for seeking.

List all active Windows audio render devices (Core Audio ground truth)

// Response:
[
  { "name": "Speakers (HD Audio)", "id": "{0.0.0...}", "isDefault": true },
  { "name": "HDMI Output", "id": "{0.0.0...}", "isDefault": false }
]

Get Windows audio device volume and mute state

// Response:
{
  "device": "Speakers (HD Audio)",
  "volume": 75,
  "muted": false
}

Set Windows audio device volume (0–100)

PUT /devices/audio/volume
Content-Type: application/json

{ "volume": 50 }

Set Windows audio device mute state

PUT /devices/audio/mute
Content-Type: application/json

{ "mute": true }

List all configured network endpoints

// Response:
[
  {
    "id": "devialet-1",
    "name": "Living Room",
    "type": "Devialet",
    "ip": "192.168.1.50"
  }
]

Add a new network endpoint

POST /devices/endpoints
Content-Type: application/json

{
  "ip": "192.168.1.50",
  "type": "devialet",
  "name": "Living Room"
}

Scan the LAN for network audio devices. Bodyless POST (send Content-Length: 0). ?protocol=mdns|ssdp|all selects the discovery protocol: mdns (default) sweeps speaker service types via mDNS/DNS-SD; ssdp sweeps UPnP MediaRenderer:1 via SSDP M-SEARCH (WiiM/LinkPlay, Sonos, TVs...); all runs both concurrently. Blocks for ~4 seconds while the multicast discovery completes. Each result carries protocol; SSDP rows add model, manufacturer and location (names come from the UPnP description XML). A row whose manufacturer is recognized also carries kind — devialet, streamsdk or linkplay, the wire dialect that drives it — plus kindSource naming the rule that fired. Derived from the description already fetched, so identification costs no extra request and no probe. An unrecognized device omits both fields rather than guessing: absent means the scan does not know, and a human still chooses. Concurrent calls are rate-limited internally (429 with Retry-After).

// Response:
[
  {
    "name": "Living Room Phantom",
    "ip": "192.168.1.50",
    "port": 80,
    "hostName": "phantom-abc123.local",
    "serviceType": "_devialet._tcp.local.",
    "alreadyConfigured": false,
    "existingId": null,
    "protocol": "mdns"
  },
  {
    "name": "ultra",
    "ip": "192.168.1.100",
    "port": 49152,
    "hostName": "",
    "serviceType": "urn:schemas-upnp-org:device:MediaRenderer:1",
    "alreadyConfigured": false,
    "existingId": null,
    "protocol": "ssdp",
    "model": "WiiM Ultra Receiver",
    "manufacturer": "Linkplay Technology Inc.",
    "location": "http://192.168.1.100:49152/description.xml"
  }
]

Remove a saved endpoint

Get endpoint volume and mute state

// Response:
{
  "volume": 40,
  "muted": false
}

Set endpoint volume (0–100). A speaker that does not answer is refused 502 ENDPOINT_UNREACHABLE rather than reported as set — this route acts on the named endpoint directly and does not soft-fall-back to the player the way /mixer/volume does

PUT /devices/endpoint/{id}/volume
Content-Type: application/json

{ "volume": 50 }

Set endpoint mute state

PUT /devices/endpoint/{id}/mute
Content-Type: application/json

{ "mute": true }

List available input sources on the endpoint

// Response:
[
  { "sourceId": "upnp", "name": "UPnP", "type": "upnp", "active": true },
  { "sourceId": "optical", "name": "Optical", "type": "optical", "active": false },
  { "sourceId": "analog", "name": "Analog", "type": "analog", "active": false }
]

Select an input source on the endpoint

PUT /devices/endpoint/{id}/source
Content-Type: application/json

{ "sourceId": "upnp" }

Get mixer settings. defaultEndpointId is what is stored; defaultEndpointResolved is the endpoint the endpoint fader would actually act on right now, with the fallback already applied, so a client never has to re-implement it. null when no endpoints are configured.

// Response:
{
  "defaultFader": "player",
  "pollIntervalMs": 22000,
  "defaultEndpointId": "living-room",
  "defaultEndpointResolved": { "id": "living-room", "name": "Living Room", "type": "wiim", "ip": "192.168.1.50" }
}

Set mixer settings. defaultFader controls which fader the dashboard volume slider and keyboard shortcuts target. defaultEndpointId names which configured endpoint the endpoint fader acts on — an empty string means “the first one in the list”, which is how it behaved when a Devialet was the only kind of endpoint there was. An id matching no configured endpoint is refused with 400 UNKNOWN_ENDPOINT rather than stored.

PUT /mixer/settings
Content-Type: application/json

// Values: "player", "device", "endpoint"
{ "defaultFader": "device" }

// Point the endpoint fader at a specific speaker (empty string = first in list)
{ "defaultEndpointId": "living-room" }

Get current volume from the active default fader (player, device, or endpoint). Returns fader type and volume (0-100). Endpoint mode resolves mixer.defaultEndpointId, falling back to the first entry in endpoints[] when it is unset or names an endpoint that is gone; soft-falls-back to player if none is configured or the speaker is unreachable, surfacing the actual fader hit in the response.

// Response (player fader):
{ "fader": "player", "volume": 75 }

// Response (device fader):
{ "fader": "device", "volume": 80, "muted": false, "device": "Speakers" }

// Response (endpoint fader):
{ "fader": "endpoint", "volume": 60, "muted": false, "endpoint": "Phantom" }

Set volume on the active default fader. Also accepts POST. Takes an absolute volume (0-100) or a relative delta, which is resolved server-side against the current level of whichever fader is active — the same contract as /player/volume, and for the same reason: a client that has to read-then-set has a dead first press and races itself on two quick presses. volume wins if both are sent. In endpoint mode the response surfaces the actual fader hit — if no endpoint is configured or the speaker call fails, the server soft-falls-back to Player_SetVolume, returns fader: "player", and re-resolves a delta against the player rather than against the level the speaker never reported.

PUT /mixer/volume
Content-Type: application/json

{ "volume": 80 }

// Relative, resolved against the active fader's current level
{ "delta": -5 }

// Response (player or device fader):
{ "fader": "device", "volume": 80, "success": true }

// Response (endpoint fader, speaker reached):
{ "fader": "endpoint", "volume": 80, "success": true, "endpoint": "Phantom" }

// Response (endpoint fader, no endpoint configured -- fell back to player):
{ "fader": "player", "volume": 80, "success": true }

Mute state of the active default fader, resolved exactly as /mixer/volume is — so volume and mute always land on the same device. fader is the one actually hit, which is how a client can tell that an unreachable speaker sent it to the player instead.

// Response (endpoint fader):
{ "fader": "endpoint", "muted": false, "endpoint": "Living Room" }

Set mute on the active default fader. Also accepts POST. Send mute for an explicit state, or toggle to invert whatever the current fader reports — the toggle exists so one button does not have to read-then-write across two round trips and race whatever else is moving the same device.

PUT /mixer/mute
Content-Type: application/json

{ "mute": true }
{ "toggle": true }

// Response:
{ "fader": "endpoint", "muted": true, "success": true, "endpoint": "Living Room" }

The window-able charms — the list the MBXHub Shell's overlay compositor reads to offer a charm as a desktop window. A charm is window-able when one of its actions is webapp <path>: that path is a hub page, so it can be a window. Charms whose actions are pure HTTP or exec have no page to host and are omitted, as is any page that resolves off this hub.

Which members, and in what order. Charms follow charmBar.order — the same list the dashboard bar uses, so a charm placed there arrives in that place here; anything unnamed keeps its load order after the named ones. Loose pages/*.html are opt-in: name a slug in charmBar.windowPages (tree.html is tree) and it appears as page.<slug>. Empty means charms only — sourcing every page put 26 members on a stock install, and a launcher that sizes to its content asked for more height than the screen. charmBar.hidden wins over an opt-in, and accepts either the bare slug or the page. id.

Visibility is the charm bar's, not this endpoint's: the same three filters the dashboard applies are applied here — nothing at all during an active party, ids in charmBar.hidden dropped, and aria dropped when ARiA is disabled — so the endpoint never publishes the id, label, icon or page of a charm the host chose to hide. Settings are read per request, so a toggle takes effect on the next call. A registration nobody has approved is not published here either, and that exclusion is not one of the three: it happens at the load, once, for every charm surface at the same time — see What is rendered, and when.

Disable with the apiDisableCharmPages setting (returns 404 when true); the compositor then falls back to its own built-in pages.

// Response:
{
  "success": true,
  "data": {
    "members": [
      {
        "windowId": "charm.mixer",
        "page": "/pages/mixer.html",
        "label": "Mixer",
        "icon": "<svg viewBox='0 0 16 16' …></svg>",
        "source": "charm"
      }
    ]
  }
}

icon comes from the charm’s own value, or from the expand entry that supplied the page when the charm has none of its own — most shipped charms keep their icon only on the expand entry, so reading the top level alone answered null for almost all of them until 2026-08-18. The shipped charms carry inline SVG markup rather than an emoji — a consumer must RENDER it, not look up a glyph. (This example said "🎛" and showed a bare array until 2026-08-18; both were wrong against the live response.)

Top-level pages/*.html files are listed too, as windowId: "page.<slug>" with source: "page", NO icon and a label derived from the filename — so dropping an HTML file in makes it window-able. A page a charm already offers is skipped rather than listed twice. A missing icon is normal here, never an error.

The launchable list a HUD-like surface draws: charms that declare a launch or launchFallback target and claim the overlay placement. Answers { "local": true, "services": [ { "id", "label", "icon", "launchKind" } ] }, where launchKind is scheme or exe — enough for a client to say what pressing it does, and the target itself is never returned: that is the operator’s business on the approval row.

Off this machine it answers an empty list, with local: false — “this machine” is loopback or a request that arrived on the address it came from, so a page reaching the hub by the machine’s own LAN address counts (before 2026-09-08 only loopback did, and the charm bar drew no launch charms at all). The press is local-only, and a remote HUD drawing tiles that cannot work would be a lie.

The placement condition is load-bearing rather than decoration: without it every Tools-menu launch charm would appear in the HUD as a side effect of existing, reaching a surface its author never asked for and the operator never saw on the row. overlay is how a charm asks for the HUD. A charm with no registration block is listed — a manifest in the charms folder was put there by the person whose machine this is, and the launcher reads the same rule.

Start it. Body-less, and there is no target parameter, ever: what runs is the manifest’s own launch target, or its optional launchFallback after an unavailable target or failed dispatch — both strings are shown on the approval row — so what was approved and what starts cannot come apart. Local callers only.

A second press RAISES rather than starting a second copy. When the charm’s executable is already running under the hub’s single-instance guard, its window is restored and brought to the front, and the answer says which happened: { "launched": false, "raised": true } — exactly one of the two is ever true, and launchKind rides along either way. Pressing an icon again is the clearest statement of what you want in front, so it is answered rather than ignored. Scheme launches are handed to the shell and whatever it does with a repeat is the handler’s business, not ours.

Refusals: 403 NOT_LOCAL (not on the machine MBXHub runs on); 403 API_READ_ONLY when apiReadOnlyMode is set — read-only is the API’s posture and being local does not exempt it, which is the same refusal /charms/register has always given; what stays unrestricted is the console, so the Tools-menu item and the Charm Manager still launch; 404 NOT_FOUND (no such charm); 403 LAUNCH_REFUSED, whose message is the launch policy’s own reason — not active, no target declared, a denied scheme, a scheme the operator’s allow-list does not name, or a registered charm’s executable that is not its observed image; 409 LAUNCH_NOT_STARTED (allowed, and nothing happened). That last one no longer means “already running” — that case is the raise above. It now means the shell threw, the guard is tracking a process that has gone, or the app is running with no window to raise, which is the log line to read: a launch that produced no window is a wrong target, a scheme handler that swallowed it, or an app that exited its splash, and the hub says so by name.

The vocabulary a charm may ask in — every capability this build knows, in the words a person answers in. Ungated and read-only: it states the vocabulary, not anyone's grants. Read it before registering, because registration refuses a scope this build does not know, and being told the words only after being refused for using the wrong one is not a contract anyone can build against.

scope is the wire name (area:verb) and never appears in name — someone agreeing to something should not have to know the route table to know what they said yes to. name is what the operator sees, named for what they are exposing rather than for what the API does (“Remote control”, not “aria:input”). agreeing is the one line they are agreeing to. maturity is default or lab. reserved true means withheld from every caller, and reservedReason says what is missing — reserved entries are listed rather than hidden, because a capability nobody can have is still something an integrator needs to see, and hiding it only turns “reserved” into “undocumented”.

// Response:
{
  "success": true,
  "data": {
    "apiVersion": "1",
    "capabilities": [
      {
        "scope": "playback:control",
        "name": "Playback control",
        "agreeing": "play, pause, skip, seek and change the volume",
        "maturity": "default",
        "reserved": false
      }
    ]
  }
}

The twelve, as shipped.

Three of the twelve are recorded but not enforced yet. The hub’s scope table has no row naming playback:control, library:read or bridge:internet, so no route demands one and the gate never consults them: granting or withholding one of those three changes nothing a caller can observe in this build, and playback and library reads answer a ticketed caller exactly as they answer an unregistered one. Ask for what you actually use anyway — the operator’s answer is recorded against the charm and is what a later build enforces — and expect a refusal to start being a refusal without the vocabulary changing. The Charm Manager marks those rows the same way.

render:spout was the fourth of those until 2026-09-07, and is enforced now — but not by a route. The scope table still has no row for it, and that is correct rather than an oversight: what it gates is not a request. /charms/pages withholds sourceSpec from a member whose registration does not hold the grant and sets blocked to render:spout, and the Shell re-checks authorization every five seconds while a source is hosted. So the capability is observable — a charm without it gets no picture — while ScopeTable.Gates still answers no, which is the honest answer to the narrower question that table asks.

Local callers only, and the body must be declared as JSON. Registration is accepted only from the machine MBXHub runs on (request.IsLocal) — a hub that could be enrolled from across the network is a hub anyone on the network can enroll themselves into, so this is not a policy that loosens. It is checked first, ahead of read-only mode and ahead of reading a byte of the body, so a remote caller is told NOT_LOCAL whatever it posted. The request must also carry Content-Type: application/json (parameters such as ; charset=utf-8 are fine); anything else is 415. That second requirement closes the browser-driven path a locality check cannot: a text/plain POST is a CORS-simple request, so a page the operator happens to be visiting could fire one at localhost with no preflight and have the write land, and application/json is not on that list.

Body is a charm manifest — the same JSON an installed charm file holds — read as UTF-8, at most 64 KB. id is required, must be a string, and must be publisher-namespaced: at least one dot, at most 128 characters, letters/digits/./-/_ only, no / \ : and no .. segment. The dot is not house style — no built-in charm id contains one, so a registered id can never collide with a built-in that the next upgrade re-seeds by name, and the id is safe to use as a file name.

// POST /charms/register
{
  "id": "com.example.thing",
  "schemaVersion": 2,
  "label": "Thing",
  "publisher": "Example Ltd",
  "version": "1.0",
  "kind": "proc",
  "scopes": ["playback:control"],
  "scopeReasons": {
    "playback:control": "to pause the music when a call comes in"
  }
}

// Response:
{
  "success": true,
  "data": {
    "charmId": "6f1c2f42-1d0c-4d2a-9f5f-7c3f2b0a91de",
    "status": "pending",
    "restartRequired": [],
    "apiVersion": "1"
  }
}

Status. pending means registered, not yet approved: no capability is granted, and every open endpoint behaves for the charm exactly as it does for an unregistered caller. active means the operator has approved it. revoked means they took the approval back — the record stays, the credential is gone, and every grant is released. pending is the only status the hub itself ever assigns — nothing in a request can ask for active.

restartRequired — what is registered but not yet on screen. The placements this registration declared that MusicBee itself hosts (menu, node, tab, hotkey, status). They are registered at the plugin's Initialise, so they appear when MusicBee next starts, not now. [] when there are none, and present on every 200 — including a re-registration of the same entry, because the answer describes the MusicBee session that is running, not what changed since last time. It is absent from a refusal, where nothing was registered. Names are reported as the manifest spelled them, deduplicated case-insensitively with the first spelling kept; a placement nothing hosts (rail, rail-menu, window, overlay, or a value this build does not know) is not listed, because claiming it waits on MusicBee would be a promise that never comes true.

How a charm receives its ticket. Approval happens at the console (MBXHub settings → the Charm Manager tab — a dev-mode tab, hidden until seven clicks on the version label reveal it alongside the debug row) and no REST route approves anything. Registration is how the charm finds out: the next POST /charms/register from loopback carrying the same id, once the operator has approved, answers status: "active" with grantedScopes and a plaintext ticket — once. The parked plaintext is taken as it is handed over, so registering again answers active and grantedScopes with no ticket. Both fields are omitted from a pending answer, so the shape a not-yet-approved caller sees is byte-for-byte what it was. Store the ticket the moment you receive it — no route re-reads it.

A caller the hub could not resolve does not collect the ticket either. When the peer lookup runs and cannot say which process is calling, the answer is still active and still states grantedScopes, the plaintext stays parked, and the body carries "ticketWithheld": "caller-unresolved". Registering again from a connection the hub can resolve delivers it, exactly once as before. That field is what tells this apart from the ordinary “you already collected it” answer, which is otherwise byte-identical and has the opposite remedy; it is absent from every other answer rather than sent as null, so its presence is the whole signal. It applies to every kind, not only proc — what failed is who is calling, which is not a question about substrate.

// The registration AFTER the operator approves:
{
  "success": true,
  "data": {
    "charmId": "6f1c2f42-1d0c-4d2a-9f5f-7c3f2b0a91de",
    "status": "active",
    "grantedScopes": ["playback:control"],
    "ticket": "3Qk1x…43 characters of base64url…",
    "restartRequired": [],
    "apiVersion": "1"
  }
}

A hub restart before delivery loses the parked ticket — and approving again is the way out. The plaintext is held in the hub's memory until it is claimed — only its sha256: digest is ever written to disk — so if MBXHub restarts between the approval and the charm's next registration, the minted ticket can never be delivered. The record is still active and still holds that ticket's digest; it just answers registrations without a ticket, and every gated call it makes answers 401 TICKET_UNKNOWN. The operator ticks the row and clicks Approve again, and a new credential is minted, which the charm collects on its next registration: an approval nothing ever collected has nothing running on it to log out, and the Charm Manager tells the two apart — “approved; waiting for the charm to announce itself” against “running with a credential”. No revoke is needed for this. Approving again on a credential the charm HAS collected still adjusts its grants and keeps that credential rather than minting a second one, so a running charm is never logged out by a grant change; re-issuing to a running charm is revoke, then approve. A registration written by an older build carries no delivery marker at all, and its absence reads as collected — so upgrading never turns a charm that is running into one the next Approve would re-issue a credential to; only an approval this build minted and has not yet handed over is marked uncollected.

Registering again is one record, not two. The same id posted a second time answers 200 with the same charmId and the status the registration already had, and keeps its original registration time. The manifest half is the caller's to change — a later version, a new label, different scopes: the stored file is rewritten with what was posted. The hub-owned half — charmId, status, the registration time, the observed image and its digest, the tier, the ticket digest, the declined and banned lists, and the granted scopes — survives that rewrite, so a re-registration can never reset or advance the operator's decision. An application that re-announces on every launch therefore accumulates nothing. The hub id is the one exception: it is re-stamped from the running install on every registration, and a record that named a different hub is severed by that announcement — status back to pending, the ticket digest gone, every grant released, and an approval whose plaintext was never collected discarded with it. A reset network setup is therefore a real start-over: the operator approves again, deliberately, on the hub that exists now. Declines, bans and the observed image are not cleared by a severing — a reset is the operator's own act, and none of those is an approval to take back, so re-keying the hub cannot launder a ban away. A record naming no hub at all is not a severing: there is nothing for it to have changed from.

Announcing from a different executable takes the approval back. For a proc charm the hub resolves the image behind the registering connection on every announcement. When an active record was approved for one image and the announcement comes from another, the record goes back to pending and the ticket digest is cleared, so the old credential resolves to nothing and every gated call it makes answers 401 TICKET_UNKNOWN; an approval whose plaintext was never collected is discarded with it. The registration still succeeds — the answer is pending, with no grantedScopes and no ticket, and the launch action refuses for the same reason, so a charm cannot move its own gate and keep the yes. The grants stay on the record and are re-confirmed when the operator approves again, which is what mints a new ticket. A path that differs only in case, or only in .. segments that resolve to the same file, is not a move. A registration whose caller could not be resolved is not an observation at all: nothing is written — not the image path, not its digest, not the tier — so what was observed before stands, and an announcement the hub cannot identify can neither move the gate nor erase what is on the record.

Changing either declared target, launch or launchFallback, does the same, and for the same reason. The operator approved a charm having read the exact string it said it would start; an active record whose next announcement declares a different one goes back to pending with its credential cleared, so the new target is approved deliberately or not at all. Compared case-insensitively, and a manifest that drops the field and one that sends "" are saying the same nothing — neither is a change from the other.

Changing where the charm appears does the same, and that is the third trigger. The placements the operator approved are the ones on the Charm Manager row: the charm's own placement, plus whatever its expand[] entries resolve to, deduplicated. An active record whose next announcement declares a different set goes back to pending with its ticket cleared — a placement added, one removed, or both. It is a set, compared case-insensitively: order and duplicates are nothing, and labels, icons and actions are not part of it, so an ordinary version bump moves nothing. Adding a second rail entry to a charm that is already a bar button changes no set; adding a menu entry to a charm that declared only rail entries does, and that charm is approved again before it holds a credential.

Rewording why you want a capability does the same, and that is the fourth trigger. The sentence in scopeReasons is the basis of the operator’s consent — it is the only thing about the request they read in your words, and it sits on the approval row beside the capability’s name. An active record whose next announcement gives a different sentence for a scope it already asked for goes back to pending with its ticket cleared, so the new words are approved deliberately or not at all. A charm approved on “to show your now-playing artwork” cannot come back saying “to index your library for our servers” and carry on with the credential it was given. Compared trimmed and case-sensitively; a scope that was not requested before has no prior sentence and is not this trigger. It does mean the first announcement in which an already-approved charm starts sending sentences costs it its approval once — the row goes from no reason given to your words, which is the row reading differently — so adopt scopeReasons in a release you would expect a re-approval in.

The fifth trigger is about the hub, not the charm. A record approved under a different hub install — a charms folder carried to another machine — goes back to pending on its first announcement there, with its ticket cleared, and this one also releases the grants: the person who granted them is not the person running this hub. The four declaration triggers keep the grants because the same person is re-approving a changed program; this one starts over.

Re-registration prunes grants to what is still asked for. On every announcement the granted set is intersected with the incoming manifest's scopes, so a capability the publisher stopped asking for is released rather than held indefinitely. The sharp edge, stated so it is a decision and not a surprise: a manifest that stops declaring scopes at all releases everything. Declines and bans are not pruned — a grant is released when the publisher stops asking, but a NO is not the publisher's to withdraw by shipping a version that omits the scope.

An id is claimed by the publisher the operator approved. Once a record is active or revoked and names a publisher, that id is re-registered only by a caller whose publisher is non-empty and ordinal-equal to the one on file; an empty incoming publisher and a mismatch both answer 409 ID_CLAIMED. A record that names no publisher claims nothing: an empty stored publisher is a string no caller could ever equal, so such a record would have locked its id forever — for its own author most of all — and nothing is at stake in admitting it, because the hub refuses to approve a record that declares no publisher, so an anonymous record holds no grant and no credential. A pending record is still overwritable: nothing has been granted to it, so there is nothing to inherit, and refusing would let anyone park an id no one could then register. Revoking does not put the id back on the shelf.

The rule is enforced where the write happens, inside the registry's own lock, and the route checks it first only as a fast path. That matters because an approval landing between the route's read and its write would otherwise admit a second publisher against a state that no longer existed — and hand them the plaintext ticket parked for the first.

A stored file that cannot be read is replaced rather than honored, so a caller can always recover by registering again. Its old charmId is lost, which is the position a reset leaves it in too.

Every scope you ask for carries one sentence of your own saying why. scopeReasons is a top-level object mapping each scope name to a single sentence, and the person approving you reads that sentence verbatim, beside the capability’s name, on the Charm Manager row — and again on the runtime prompt, labeled They say: so they know which sentence is yours and which is ours. It is the only thing about your request they see in your words. Write it as the truth, for the person, not for us: a rationale that does not match what the application then does is what gets an extension revoked.

Declare schemaVersion: 2 and give every scope its sentence — that is how a charm written to this document registers. Version 1 (declared, or absent, which reads as 1) is tolerated for manifests that predate the field and may omit scopeReasons entirely; such a charm registers exactly as it always did, and its approval row says no reason given against every capability it asks for. The two lists are otherwise the same set: a sentence for a scope you did not request is refused, not ignored. Each sentence is one line of at most 200 characters, trimmed on the way in — it gets one row beside the capability’s name, and a sentence carrying its own line breaks is laying out somebody else’s console. It is stored on the record verbatim; nothing here re-encodes it, and no & or angle bracket in it is escaped away.

Rewording a sentence takes the approval back. A re-registration whose rationale for an already-requested scope changes returns the record to pending and clears the ticket, exactly like the other declaration triggers — it is the fourth of them, described above. Compared trimmed and case-sensitively, unlike the launch and placement compares: this is prose a person read, and re-capitalizing a sentence changes what it says to them. Adding a scope that was not requested before is not this trigger — there is no prior sentence to have changed, and the grant pruning rule already leaves it ungranted until the operator answers.

Refusals.

Two gates sit in front of the route rather than in it. While kiosk mode is on, and while a party is active for a non-local caller, the router redirects (302) anything outside the allowed surface before a handler runs; registration is on neither allow-list, so it is refused with a redirect rather than an error body. Localhost is exempt from the party redirect. The Basic password gate, when enabled, applies as it does to any other remote request.

Read one registration back. It reports a decision the operator has already made and changes nothing, so it carries no gate of its own: read-only mode does not refuse it, and neither does apiDisableCharmPages. The id is a path segment, so percent-encode it.

The two front gates still apply. The kiosk and party redirects described above are path-based, not endpoint-based — /charms/ is on neither allow-list — so on a kiosk box, and for a non-local caller while a party is active, this read is redirected (302) exactly as registration is. The Basic password gate applies too. “No gate of its own” is a statement about the handler, not about what reaches it.

// GET /charms/com.example.thing
{
  "success": true,
  "data": {
    "id": "com.example.thing",
    "kind": "proc",
    "publisher": "Example Ltd",
    "version": "1.0",
    "status": "active",
    "tier": "verified",
    "grantedScopes": ["playback:control"],
    "requestedScopes": ["playback:control"]
  }
}

• id, publisher, version — as the manifest declared them. A field the manifest did not carry is omitted from the response rather than sent as null.
• kind — the declared kind, or page when the manifest declared none.
• status — pending, active or revoked, as above. A hand-written registration block with no status describes as pending, the status every registration starts at.
• tier — trust tier, and it is observed, not declared. For a proc charm the hub resolves the peer process behind the registering connection and verifies that image's signature at registration time, then states the rung the evidence earns:
  • halrad-signed — the signature verifies and chains to our pinned certificate.
  • verified — it chains, but not to us.
  • unsigned — no signature, an unreadable one, or any WinVerifyTrust failure. A tampered image and an expired certificate both land here deliberately: a patched binary must never be quieter than an honest unsigned build, and a publisher should not be punished a rung for a lapsed certificate.
  • pinned — a name, fixed so the wire value cannot be argued about later. Nothing in this build produces it.
  page and endpoint charms carry no tier at all and the field is absent: a page is HTML this hub serves and an endpoint answers HTTP somewhere we cannot see, so calling either “unsigned” would be a checked negative nobody checked. A proc whose peer cannot be resolved is left untiered: that lookup writes nothing at all — not the image path, not its digest, not a tier — so a charm nothing has ever resolved carries no tier rather than unsigned, and one that was resolved before keeps what that lookup found. Failing to determine is not evidence in either direction; the one-shot credential is withheld on exactly that answer instead (see How a charm receives its ticket). What a tier does: it sets how loudly a grant is asked for at the console. It is never an input to the capability gate and never decides what an issued ticket may do.
• grantedScopes — what the operator has granted. Empty until they do, and stated as empty rather than omitted, so a client can tell “nothing granted” from “field missing”.
• requestedScopes — what the manifest asked for. Asking is not being granted; these two lists are answers to different questions and a client must not read one for the other.

It never returns the registry's private half. The observed image path and its signer digest, the ticket digest, and the declined, banned and licensed lists are recorded against a registration and are not on this response under any name — licensedScopes in particular is not surfaced here or on any other route. This endpoint is what a charm is told about itself, not the record kept about it.

404 NOT_FOUND covers every “no such registration”: an id that is not registered, an id that could never have been registered (no dot, a path separator, empty), and a charm file that carries no registration — one somebody shipped or hand-wrote is not something that announced itself. That is also what keeps this prefix off its neighbors: /charms/pages and /charms/register are matched as static routes first, and neither name could be a registered id anyway.

Invoke any MusicBee API method by name