Recent API Surfaces

This page highlights recent Haptique OS API and feature surfaces for developers building mobile apps, local remotes, Music Services clients, and integration tooling.

OS API Mirrors

Most OS-local JSON APIs are mounted at:

/app/os
/api/os
/v1/os

New external clients should prefer /v1/os. Existing mobile and local app clients may continue using /app/os.

Mobile Home and Preferences

Method	Path	Purpose
GET	/preferences/home	Load home screen preferences
POST	/preferences/home	Save home screen preferences
GET	/preferences/home/favorites	Load favorite device keys for the home screen
POST	/preferences/home/favorites	Save favorite device keys
GET	/bootstrap	Hydrate mobile home with devices, spaces, programs, state, media, and docs summary

Favorites are stored as favoriteDeviceKeys. The response also expands each key into roomId and deviceId for room-aware clients.

Logical Device Metadata and Controls

Method	Path	Purpose
POST	/devices/:id/metadata	Update device tags, primary room, or remoteSource status
GET	/devices/:id/apps	List launchable apps for app-capable devices
POST	/devices/:id/apps/:appId/launch	Launch an app on a supported device
GET	/devices/:id/equalizer	Read equalizer and sound-mode command state
POST	/devices/:id/equalizer	Dispatch equalizer or sound-mode controls
GET	/devices/:id/scenes	List device scenes when exposed by the driver

POST /devices/:id/metadata accepts tags, room, and remoteSource. Updating room also syncs room-space membership through the OS space service.

Activities, Zones, Zone Groups, and Macros

Method	Path	Purpose
GET	/activity-presets	List activity presets
POST	/activity-presets/:id/run	Run an activity preset
GET	/zones	List zones with resolved device and program references
POST	/zones/:id/volume	Set zone volume
POST	/zones/:id/program/run	Run a zone-assigned program
GET	/zone-groups	List zone groups
POST	/zone-groups/save	Save a zone group
POST	/zone-groups/:id/remove	Remove a zone group
POST	/zone-groups/:id/zones/assign	Assign zones to a group
GET	/macros	List macros
POST	/macros/save	Save a macro
POST	/macros/:id/run	Run a macro

These routes are part of the OS-local control surface. They do not replace Fleet-era integration routes.

Haptique Music Additions

Method	Path	Purpose
GET	/media-services/players	Music Services player roster
GET	/media-services/endpoints	Local and provider playback endpoints
POST	/media-services/endpoints/discover	Refresh endpoint discovery
POST	/media-services/endpoints/update	Update custom endpoint label or enabled state
POST	/media-services/endpoints/airplay/pair/start	Start AirPlay endpoint pairing
POST	/media-services/endpoints/airplay/pair/finish	Finish AirPlay endpoint pairing
GET	/media-services/radio/catalog	Internet Radio catalog
GET	/media-services/sources/INTERNET_RADIO/stations	Saved Internet Radio stations
POST	/media-services/sources/INTERNET_RADIO/stations/save	Save an Internet Radio station
POST	/media-services/sources/INTERNET_RADIO/stations/remove	Remove an Internet Radio station
POST	/media-services/library/artwork/refresh	Refresh local music artwork

The local OS app API also exposes POST /app/os/media-services/library/upload for multipart music uploads. The form field is tracks, supports up to 100 files, and accepts common audio extensions such as MP3, AAC, FLAC, WAV, AIFF, ALAC, Ogg/Opus, WMA, APE, MP4, DSF, and DFF. Uploaded files are added to the local music library and trigger a scan.

Music Remote Access

Method	Path	Purpose
GET	/media-services/remote-access/status	Read remote Music access status
POST	/media-services/remote-access/enable	Enable remote Music access
POST	/media-services/remote-access/disable	Disable remote Music access
POST	/media-services/remote-access/session	Issue a remote Music session
POST	/media-services/remote-access/session/verify	Verify a remote Music session
POST	/media-services/remote-access/reachability/probe	Record a reachability probe

These endpoints are scoped to Music Services remote access and are separate from the general /remote-access/status OS route.

Local Media Controller

Method	Path	Purpose
GET	/media-controller/state	Load local media-controller state
POST	/media-controller/control	Execute a local media action
GET	/media-controller/stream	SSE stream for now-playing state

This surface is for local controller state such as Apple Music style transport and now-playing data.

HomeKit Import and Plugin Management

Method	Path	Purpose
GET	/homekit/plugins/search	Search plugin catalog
GET	/homekit/plugins/resolve	Resolve plugin metadata
GET	/homekit/plugins/:pluginId/config-schema	Read plugin configuration schema
POST	/homekit/plugins/custom	Add a custom plugin catalog entry
POST	/homekit/plugins/:pluginId/catalog-remove	Remove a plugin catalog entry
POST	/homekit/import-accessories/resync	Refresh importable accessories
POST	/homekit/import-accessories/:accessoryId/import	Import a HomeKit accessory
POST	/homekit/import-accessories/:accessoryId/remove	Remove an imported accessory
POST	/homekit/plugin/external-accessories/sync	Plugin bridge external accessory sync
GET	/homekit/plugin/import-commands	Pull pending import commands
POST	/homekit/plugin/import-commands/:commandId/ack	Acknowledge an import command

Metadata Service

The Haptique metadata API exposes music metadata routes under /v1/music.

Method	Path	Purpose
GET	/v1/music/health	Service and provider health
POST	/v1/music/identify	Identify tracks from submitted metadata
POST	/v1/music/enrich-batch	Enrich artist and album profiles
GET	/v1/music/search?q=...&type=...&limit=...	Global metadata search

Configured providers can include MusicBrainz, Cover Art Archive, AcoustID, Last.fm, Fanart.tv, Spotify, and YouTube artwork. POST /identify, POST /enrich-batch, and GET /search require the metadata service API token.

Notes

• Keep new clients on OS-local /v1/os APIs unless they intentionally need Fleet compatibility.
• Use /media/players for normalized media-player rosters and /media-services/status for full Music Services state.
• Use server-confirmed state and SSE reconciliation for playback workflows; do not treat a successful command response as proof that a target started playback.