Music Hub AI Integration Guide

For assistants, automation scripts, and local tooling

What is stable

Automation targets the desktop hub REST API + SSE.

Current integration primitives:

• REST API for library, browsing, playlists, playback, metadata, enrichment, analytics
• SSE for library events and scan progress
• Pair/refresh auth for remote clients
• Public share bootstrap for browser-safe consumption
• AI context endpoint (/api/ai/context)

Important constraints

1. No generated /api/docs/markdown

Use:

• API Reference for Agents (this site)
• Settings > Advanced > Agent API Endpoints (in-app)

2. Remote access is authenticated

Remote and proxied calls need:

• Active desktop license
• Bearer tokens from /api/auth/pair + /api/auth/refresh
• Or MUSIC_HUB_API_TOKEN environment variable

3. Local-only routes

These must run on the desktop host (loopback):

• /api/settings/folders/rescan
• /api/database/rebuild
• /api/auth/devices

4. Pairing for agents

Agents running on the same machine as the hub can use loopback without auth. For remote agents:

1. Arm pairing from the desktop UI (Settings > Pairing)
2. Exchange pairingCode via POST /api/auth/pair
3. Use returned accessToken as Authorization: Bearer <token>
4. Refresh with POST /api/auth/refresh before expiry

Recommended patterns

Local automation (same machine)

curl http://localhost:38472/api/ping
curl http://localhost:38472/api/info
curl "http://localhost:38472/api/tracks?genre=Jazz&limit=20"

Remote automation (paired device)

# 1. Pair (once)
curl -X POST http://<hub-ip>:38472/api/auth/pair \
  -H 'Content-Type: application/json' \
  -d '{"pairingCode":"...","deviceId":"agent-1","deviceName":"automation"}'
 
# 2. Use token
curl "http://<hub-ip>:38472/api/search?q=boards+of+canada" \
  -H "Authorization: Bearer $TOKEN"

Public browser/share

Use only share bootstrap endpoints:

curl http://localhost:38472/api/share/playlist/<id>/bootstrap

User-context routes

Notes

• GET /api/tracks/:id/notes
• POST /api/tracks/:id/notes { "text": "..." }
• GET /api/playlists/:id/tracks/:trackId/notes
• POST /api/playlists/:id/tracks/:trackId/notes

Track notes are global. Playlist track notes are scoped to one playlist placement.

Collaborative playlists

Permissioned per hub. A hub must be an active member of the share with required capability:

• playlist.read — snapshot/read
• playlist.write_ops — edits
• media.stream — remote shared media
• members.invite / members.revoke — admin

Analytics for agents

• GET /api/analytics/hub-counter — total playback time, desktop vs mobile, sessions, license gate
• GET /api/analytics/play-history?days=7&limit=100 — recent plays with track details
• POST /api/analytics/hub-counter/recalculate — rebuild counter from DB (local-only)

Metadata & enrichment for agents

• GET /api/tracks/:id/metadata — full overlay (genres, tags, ISRC, barcode, MBIDs, canonical links, release facts)
• PUT /api/tracks/:id/metadata/curated — set effective genres/tags/styles
• GET /api/tracks/:id/enrichment/job — check enrichment status
• POST /api/tracks/:id/re-enrich/search — search MusicBrainz or Discogs
• POST /api/tracks/:id/re-enrich/apply — apply a candidate

Basic examples

# Hub snapshot
curl http://localhost:38472/api/info
 
# Search
curl "http://localhost:38472/api/search?q=boards+of+canada&limit=10"
 
# Watch library events (SSE)
curl -N http://localhost:38472/api/library/events
 
# Get playback counter
curl http://localhost:38472/api/analytics/hub-counter
 
# Get track metadata with enrichment
curl http://localhost:38472/api/tracks/:id/metadata

Failure modes

• 401 — remote auth missing or expired
• 403 — local-only endpoint called remotely, or license required
• 409 pairing_not_armed — pairing window expired or never armed
• 503 database_unavailable — hub DB faulted

Always check databaseHealth from /api/info before assuming the library API is usable.