Skip to content

Integration

Jump to bottom
Skila edited this page Aug 21, 2026 · 3 revisions

Integration

For bots, apps, and Subsonic clients talking to a SoundDock instance. Interactive docs on a running server: /api/docs. Machine-readable spec: /api/v1/openapi.json.

The web app uses only /api/v1. Your integration should do the same.

Authentication

Who How
Browser users (Discord on) Discord OAuth. GET /api/v1/auth/discord, callback at /api/v1/auth/discord/callback. Session cookie sd_session.
Browser users (local) POST /api/v1/auth/login with username and password. First local admin: POST /api/v1/setup when Discord is off and no users exist.
Bots and scripts API key from Admin → Integrations. Shown once. Header: Authorization: Bearer sd_...

Create keys as an administrator. Treat them like passwords.

GET /api/v1/system/info reports features.discord_login so a client can hide Discord.

Typical bot flow

  1. GET /api/v1/system/info (instance name and capabilities, no secrets)
  2. Authenticate with an API key
  3. GET /api/v1/search?q=...&type=track
  4. Play using the stream_url on the result (short-lived token). Do not use filesystem paths. SoundDock never returns them.

Stream endpoint: GET /api/v1/tracks/{id}/stream (HTTP Range). Query token if you are not sending a session or Bearer key. Optional quality: original, high, medium, low.

CORS

Browser origins may send Authorization and Content-Type. Session cookies are HttpOnly.

OpenSubsonic

Set SD_OPENSUBSONIC=true and point a Subsonic-compatible client at /rest. This is a small subset (ping, license, music folders). Paths to files on disk are never returned.

Webhooks

Create endpoints in Admin → Webhooks. SoundDock POSTs JSON:

{"event": "playback.started", "payload": {}, "ts": "2026-01-01T00:00:00Z"}

Headers:

  • Content-Type: application/json
  • X-SoundDock-Event: event name
  • X-SoundDock-Signature: sha256= plus hex HMAC of the raw body, using the secret you configured

Events you can subscribe to include playback.started and library.scan.completed.

Discord as a client

Enable the Discord extra (Extras). Invite the bot from Admin → Integrations → Discord. Users link with /link in Discord, then confirm in the web UI. Playback is library search and stream only.

Admin invite URL (authenticated admin session): GET /api/v1/admin/integrations/discord/invite

Playlists from Spotify, YouTube, SoundCloud, Apple Music

Users connect providers under Connected Services and import playlist URLs. SoundDock matches titles against your library. It does not download provider audio or bypass DRM.

Remote Import (POST /api/v1/imports/url) is separate: direct HTTP(S) media file URLs only. Playlist or watch-page URLs are rejected.

Uploads and libraries

  • Resumable uploads: POST /api/v1/uploads
  • Libraries, scan, and artwork: see /api/docs

Health

  • /healthz
  • /readyz

SoundDock

Clone this wiki locally