Haptique Music API

The Haptique Music API lets developers build local music remotes, room panels, automation apps, now-playing displays, playback endpoint bridges, and agent workflows against a Haptique OS controller.

This API is part of the Haptique OS local flow. It does not replace the Fleet cloud backend or legacy Fleet integration routes.

Base URL

Use the OS API base path for new developer apps:

text

http://<haptique-host>:8080/v1/os

Equivalent local OS API mirrors may exist at /app/os and /api/os, but external developer apps should prefer /v1/os.

Authentication

Most requests require a bearer token:

http

Authorization: Bearer <token>

Obtain a token with:

http

POST /v1/os/auth/login
Content-Type: application/json

{
  "email": "admin@example.com",
  "password": "your-password"
}

Successful responses use the standard Haptique envelope:

json

{
  "status": true,
  "message": "Human readable message",
  "data": {}
}

Developer Use Cases

The Music API is intended for:

Mobile or tablet remotes
Wall-mounted now-playing dashboards
Hardware controllers for volume, transport, and mute
Automation apps that start music, switch rooms, or run presets
Search and browse experiences for local library and connected services
Music Bridge endpoints that register as playback targets
AI or MCP tools that need normalized media-player control

Quick Start

1. List playable media players

http

GET /v1/os/media/players
Authorization: Bearer <token>

Response shape:

json

{
  "status": true,
  "message": "Media players loaded.",
  "data": {
    "players": [
      {
        "id": "logical-device-id",
        "label": "Living Room",
        "available": true,
        "playable": true,
        "capabilities": {
          "transport": true,
          "volume": true,
          "seek": true
        },
        "nowPlaying": {
          "title": "Track Title",
          "artist": "Artist",
          "playback": "playing",
          "positionMs": 42000,
          "durationMs": 214000,
          "artworkUrl": "/app/os/media-services/library/artwork/cache/example.jpg"
        }
      }
    ],
    "summary": {
      "total": 1,
      "playing": 1
    }
  }
}

2. Send a transport command

http

POST /v1/os/media/players/{playerId}/command
Authorization: Bearer <token>
Content-Type: application/json

{
  "action": "pause"
}

Supported normalized player actions:

Action	Payload
`pause`	`{ "action": "pause" }`
`resume`	`{ "action": "resume" }`
`next`	`{ "action": "next" }`
`previous`	`{ "action": "previous" }`
`seek`	`{ "action": "seek", "positionMs": 42000 }`
`set_volume`	`{ "action": "set_volume", "volume": 35 }`
`mute`	`{ "action": "mute" }`
`unmute`	`{ "action": "unmute" }`

3. Search music

http

POST /v1/os/media-services/search
Authorization: Bearer <token>
Content-Type: application/json

{
  "query": "Kind of Blue",
  "serviceKey": "LOCAL_LIBRARY"
}

Common serviceKey values:

Service key	Purpose
`LOCAL_LIBRARY`	Haptique indexed local files
`INTERNET_RADIO`	Saved internet radio stations
`SPOTIFY`	Connected Spotify account
`APPLE_MUSIC`	Connected Apple Music account
`TIDAL`	Tidal source provider when configured
`QOBUZ`	Qobuz source provider when configured

4. Play content on a target

http

POST /v1/os/media-services/play
Authorization: Bearer <token>
Content-Type: application/json

{
  "serviceKey": "LOCAL_LIBRARY",
  "contentType": "track",
  "contentId": "track-id",
  "targetType": "logical_device",
  "targetId": "logical-device-id"
}

For provider-backed content, include provider IDs or URIs returned by search or browse:

json

{
  "serviceKey": "SPOTIFY",
  "contentType": "playlist",
  "contentId": "spotify-playlist-id",
  "uri": "spotify:playlist:...",
  "contextUri": "spotify:playlist:...",
  "targetType": "logical_device",
  "targetId": "logical-device-id"
}

5. Read and manage the queue

http

GET /v1/os/media-services/queue/{targetId}?offset=0&limit=50
Authorization: Bearer <token>

Queue mutation endpoints:

Method	Path	Purpose
`POST`	`/v1/os/media-services/queue/add`	Add content to a target queue
`POST`	`/v1/os/media-services/queue/remove`	Remove a queue item
`POST`	`/v1/os/media-services/queue/move`	Reorder a queue item
`POST`	`/v1/os/media-services/queue/clear`	Clear a target queue
`POST`	`/v1/os/media-services/queue/select`	Select and play a queue item
`POST`	`/v1/os/media-services/queue/save-playlist`	Save the current queue as a playlist

Endpoint Families

Media Players

Use these endpoints when building a normalized remote UI. The server decides which logical devices are playable.

Method	Path	Description
`GET`	`/v1/os/media/players`	List playable media players
`GET`	`/v1/os/media/players/candidates`	List included and excluded media-player candidates
`POST`	`/v1/os/media/players/{playerId}/command`	Send a normalized command to one player

Media Services

Use these endpoints for service status, playback, search, source browsing, library, and queues.

Method	Path	Description
`GET`	`/v1/os/media-services/status`	Full media service status: accounts, players, sessions, presets, targets, capabilities, pending commands
`GET`	`/v1/os/media-services/players`	Music Services player roster
`GET`	`/v1/os/media-services/endpoints`	Available local and provider endpoints
`POST`	`/v1/os/media-services/endpoints/discover`	Refresh endpoint discovery
`POST`	`/v1/os/media-services/endpoints/update`	Update endpoint label or enabled state
`POST`	`/v1/os/media-services/endpoints/airplay/pair/start`	Start AirPlay endpoint pairing
`POST`	`/v1/os/media-services/endpoints/airplay/pair/finish`	Finish AirPlay endpoint pairing
`GET`	`/v1/os/media-services/sources`	List source providers
`GET`	`/v1/os/media-services/sources/{providerKey}/browse`	Browse a provider source
`GET`	`/v1/os/media-services/sources/{providerKey}/library`	Provider library browse alias
`POST`	`/v1/os/media-services/search`	Search content
`POST`	`/v1/os/media-services/play`	Start playback
`POST`	`/v1/os/media-services/command`	Send target-level playback command
`POST`	`/v1/os/media-services/transfer`	Transfer playback or queue to another target
`POST`	`/v1/os/media-services/presets/save`	Save a media preset
`POST`	`/v1/os/media-services/presets/remove`	Remove a media preset

Library

Use library endpoints for local-library apps, browse pages, playlist tools, and metadata displays.

Method	Path	Description
`GET`	`/v1/os/media-services/library`	Local library summary
`GET`	`/v1/os/media-services/browse/library`	Browse local library
`GET`	`/v1/os/media-services/library/home`	Home screen library sections
`GET`	`/v1/os/media-services/library/albums`	List albums
`GET`	`/v1/os/media-services/library/albums/{id}`	Album detail
`GET`	`/v1/os/media-services/library/artists`	List artists
`GET`	`/v1/os/media-services/library/artists/{id}`	Artist detail
`GET`	`/v1/os/media-services/library/tracks`	List tracks
`GET`	`/v1/os/media-services/library/playlists`	List playlists
`GET`	`/v1/os/media-services/library/playlists/{id}`	Playlist detail
`POST`	`/v1/os/media-services/library/playlists/save`	Save a playlist
`POST`	`/v1/os/media-services/library/playlists/tracks/add`	Add a track to a playlist
`GET`	`/v1/os/media-services/library/folders/browse`	Browse storage folders
`POST`	`/v1/os/media-services/library/folders/save`	Save watched folders
`POST`	`/v1/os/media-services/library/rescan`	Rescan local library
`POST`	`/v1/os/media-services/library/artwork/refresh`	Refresh cached artwork

The local OS app API also exposes POST /app/os/media-services/library/upload for multipart uploads with the tracks form field. Uploaded tracks are added to the local music library and trigger a scan.

Metadata Graph and Profiles

Use these endpoints for richer music-library experiences.

Method	Path	Description
`GET`	`/v1/os/media-services/library/metadata-graph`	Full metadata graph
`GET`	`/v1/os/media-services/library/smart-views`	Smart library views
`GET`	`/v1/os/media-services/library/graph/search`	Search graph entities
`GET`	`/v1/os/media-services/library/graph/artists/{id}`	Graph artist profile
`GET`	`/v1/os/media-services/library/graph/albums/{id}`	Graph album profile
`GET`	`/v1/os/media-services/library/graph/compositions/{id}`	Graph composition profile
`GET`	`/v1/os/media-services/profile`	Current music profile
`POST`	`/v1/os/media-services/profile/markers/save`	Save a profile marker
`POST`	`/v1/os/media-services/profile/markers/remove`	Remove a profile marker
`POST`	`/v1/os/media-services/profile/filters/save`	Save a profile filter
`POST`	`/v1/os/media-services/profile/filters/remove`	Remove a profile filter
`POST`	`/v1/os/media-services/library/identity-links/save`	Link metadata identities
`POST`	`/v1/os/media-services/library/identity-links/split`	Split linked identities

Groups, DSP, and Remote Access

Method	Path	Description
`GET`	`/v1/os/media-services/groups`	List music groups
`POST`	`/v1/os/media-services/groups/save`	Create or update a group
`POST`	`/v1/os/media-services/groups/remove`	Remove a group
`GET`	`/v1/os/media-services/dsp/profiles`	List DSP profiles
`POST`	`/v1/os/media-services/dsp/profiles/save`	Save a DSP profile
`POST`	`/v1/os/media-services/dsp/profiles/remove`	Remove a DSP profile
`GET`	`/v1/os/media-services/remote-access/status`	Remote-access capability/status
`POST`	`/v1/os/media-services/remote-access/enable`	Enable remote access where supported
`POST`	`/v1/os/media-services/remote-access/disable`	Disable remote access
`POST`	`/v1/os/media-services/remote-access/session`	Create a remote access session
`POST`	`/v1/os/media-services/remote-access/session/verify`	Verify a remote access session
`POST`	`/v1/os/media-services/remote-access/reachability/probe`	Record a remote reachability probe

Internet Radio

Method	Path	Description
`GET`	`/v1/os/media-services/radio`	Internet Radio catalog
`GET`	`/v1/os/media-services/radio/catalog`	Internet Radio catalog alias
`GET`	`/v1/os/media-services/radio/channels`	Internet Radio channel alias
`GET`	`/v1/os/media-services/sources/INTERNET_RADIO/stations`	Saved stations
`POST`	`/v1/os/media-services/sources/INTERNET_RADIO/stations/save`	Save a station
`POST`	`/v1/os/media-services/sources/INTERNET_RADIO/stations/remove`	Remove a station

Music Bridge Endpoints

Music Bridge lets a developer app or device register itself as a Haptique playback target.

Register a bridge endpoint

http

POST /v1/os/media-services/bridge/endpoints/register
Authorization: Bearer <token>
Content-Type: application/json

{
  "id": "kitchen-display",
  "label": "Kitchen Display",
  "subtitle": "Raspberry Pi endpoint",
  "controlUrl": "http://192.168.1.40:4545",
  "streamBaseUrl": "http://192.168.1.40:4545/streams",
  "capabilities": {
    "canPlay": true,
    "canPause": true,
    "canSeek": true,
    "canSetVolume": true,
    "canMute": true,
    "canChangeTrack": true,
    "localStreamSupport": true,
    "supportedProtocols": ["hos_music_bridge", "http_stream"],
    "codecs": ["mp3", "aac", "flac"],
    "supportsLossless": true
  },
  "metadata": {
    "platform": "linux-arm64",
    "agentVersion": "1.0.0"
  }
}

After registration, Haptique discovers the endpoint as a music_bridge:<id> target. When playback starts, Haptique sends commands to:

text

POST <controlUrl>/commands

Example command delivered to the endpoint:

json

{
  "action": "play_media",
  "targetId": "music_bridge:kitchen-display",
  "endpointId": "kitchen-display",
  "payload": {
    "streamUrl": "http://haptique-host:8080/v1/os/media-services/library/stream/track-id",
    "transport": {
      "mode": "pull_url",
      "url": "http://haptique-host:8080/v1/os/media-services/library/stream/track-id",
      "title": "Track Title",
      "subtitle": "Artist - Album",
      "artworkUrl": "http://haptique-host:8080/..."
    }
  }
}

The endpoint should acknowledge commands with a JSON response:

json

{
  "ok": true,
  "acknowledged": true,
  "sessionId": "kitchen-display-session-1"
}

Bridge management endpoints:

Method	Path	Description
`GET`	`/v1/os/media-services/bridge/endpoints`	List registered bridge endpoints
`POST`	`/v1/os/media-services/bridge/endpoints/register`	Register or update a bridge endpoint
`POST`	`/v1/os/media-services/bridge/endpoints/remove`	Remove a bridge endpoint

Live State

For live app updates, use the OS state stream:

http

GET /v1/os/state/stream?accessToken=<token>

Use /v1/os/media-services/status as the snapshot refresh endpoint when the app reconnects or needs to reconcile player, queue, and account state.

OpenAPI

The interactive OpenAPI document is available in the wiki at:

text

/haptique-os-api.openapi.json

The current OpenAPI includes the canonical media-player endpoints and the core media-service search/play/control endpoints. This wiki page documents the broader music API surface exposed by the running Haptique OS server.

Implementation Notes

Prefer /v1/os/media/players for remote-control player rosters because it returns normalized playable devices.
Use /v1/os/media-services/status for full music-service state, service accounts, sessions, presets, targets, and capabilities.
Use server-confirmed state from status or state stream instead of assuming playback succeeded only because a command request returned status: true.
Treat available, playable, and capabilities as runtime values. They can change when devices disconnect, providers expire, or endpoints re-register.
Keep third-party apps on the Haptique OS local API. Do not call Fleet-era /integration/* routes unless you are intentionally building Fleet compatibility.

Haptique Music API ​

Base URL ​

Authentication ​

Developer Use Cases ​

Quick Start ​

1. List playable media players ​

2. Send a transport command ​

3. Search music ​

4. Play content on a target ​

5. Read and manage the queue ​

Endpoint Families ​

Media Players ​

Media Services ​

Library ​

Metadata Graph and Profiles ​

Groups, DSP, and Remote Access ​

Internet Radio ​

Music Bridge Endpoints ​

Register a bridge endpoint ​

Live State ​

OpenAPI ​

Implementation Notes ​

Haptique Music API

Base URL

Authentication

Developer Use Cases

Quick Start

1. List playable media players

2. Send a transport command

3. Search music

4. Play content on a target

5. Read and manage the queue

Endpoint Families

Media Players

Media Services

Library

Metadata Graph and Profiles

Groups, DSP, and Remote Access

Internet Radio

Music Bridge Endpoints

Register a bridge endpoint

Live State

OpenAPI

Implementation Notes