Generated REST API Reference

This reference is generated directly from the Rust OpenAPI registry in the SnapDog repository. For authentication, usage guidance, and complete examples, read the REST API guide.

Contract: SnapDog REST API 1.0.0 · OpenAPI 3.1.0

Endpoints

system

System and platform administration endpoints

Method	Endpoint	Summary	Request	Success response
GET	/api/v1/system/listeners	List every network listener of the server.	—	array<Row>
GET	/api/v1/system/status	Retrieve basic system status statistics.	—	SystemStatus
GET	/api/v1/system/updates	Read the state of the container updater sidecar.	—	UpdateStatus
POST	/api/v1/system/updates/apply	Apply the available update now.	—	UpdateStatus
POST	/api/v1/system/updates/check	Ask the sidecar to look for a newer release now.	—	UpdateStatus
POST	/api/v1/system/updates/config	Change the update mode and maintenance window of the sidecar.	UpdateConfig	UpdateStatus
GET	/api/v1/system/version	Retrieve application and platform version details.	—	VersionInfo

zones

Multi-zone control, playback, and presence management

Method	Endpoint	Summary	Request	Success response
GET	/api/v1/zones	Get all zones details	—	array<ZoneInfo>
GET	/api/v1/zones/count	Get total number of zones	—	integer
GET	/api/v1/zones/{zone_index}	Get zone details by index	—	ZoneInfo
GET	/api/v1/zones/{zone_index}/clients	Get zone clients index list	—	array<integer>
GET	/api/v1/zones/{zone_index}/cover	Get zone cover art image	—	—
GET	/api/v1/zones/{zone_index}/icon	Get zone emoji icon	—	string
GET	/api/v1/zones/{zone_index}/mute	Get zone mute status	—	boolean
PUT	/api/v1/zones/{zone_index}/mute	Set zone mute status	boolean	—
POST	/api/v1/zones/{zone_index}/mute/toggle	Toggle zone mute status	—	—
GET	/api/v1/zones/{zone_index}/name	Get zone name	—	string
POST	/api/v1/zones/{zone_index}/next	Skip to next track	—	—
POST	/api/v1/zones/{zone_index}/next/playlist	Switch to next playlist	—	—
POST	/api/v1/zones/{zone_index}/pause	Pause zone playback	—	—
POST	/api/v1/zones/{zone_index}/play	Resume zone playback	—	—
POST	/api/v1/zones/{zone_index}/play/playlist	Play unified playlist	PlaylistPayload	—
POST	/api/v1/zones/{zone_index}/play/playlist/by-id	Play playlist by playlist_id	PlaylistByIdPayload	—
POST	/api/v1/zones/{zone_index}/play/playlist/{playlist_index}/track	Play track in a playlist	integer	—
POST	/api/v1/zones/{zone_index}/play/subsonic/album/{album_id}	Play a Subsonic album	—	—
POST	/api/v1/zones/{zone_index}/play/subsonic/{track_id}	Play Subsonic track by ID	—	—
POST	/api/v1/zones/{zone_index}/play/track	Play specific track index	integer	—
POST	/api/v1/zones/{zone_index}/play/url	Play arbitrary audio stream URL	string	—
GET	/api/v1/zones/{zone_index}/playback	Get zone playback status	—	string
GET	/api/v1/zones/{zone_index}/playlist	Get zone playlist index	—	integer
PUT	/api/v1/zones/{zone_index}/playlist	Set zone playlist	integer	—
GET	/api/v1/zones/{zone_index}/playlist/by-id	Get zone playlist reference	—	string
PUT	/api/v1/zones/{zone_index}/playlist/by-id	Set zone playlist by playlist_id	string	—
GET	/api/v1/zones/{zone_index}/playlist/count	Get playlist track count	—	integer
GET	/api/v1/zones/{zone_index}/playlist/info	Get active playlist summary info	—	ZonePlaylistInfo
GET	/api/v1/zones/{zone_index}/playlist/name	Get active playlist name	—	string
GET	/api/v1/zones/{zone_index}/presence	Get presence occupancy status	—	boolean
PUT	/api/v1/zones/{zone_index}/presence	Set presence occupancy status	boolean	—
GET	/api/v1/zones/{zone_index}/presence/enable	Get presence detection enable status	—	boolean
PUT	/api/v1/zones/{zone_index}/presence/enable	Set presence detection enable status	boolean	—
GET	/api/v1/zones/{zone_index}/presence/timeout	Get presence timeout delay	—	integer
PUT	/api/v1/zones/{zone_index}/presence/timeout	Set presence timeout delay	integer	—
GET	/api/v1/zones/{zone_index}/presence/timer	Get presence timer active status	—	boolean
POST	/api/v1/zones/{zone_index}/previous	Skip to previous track	—	—
POST	/api/v1/zones/{zone_index}/previous/playlist	Switch to previous playlist	—	—
GET	/api/v1/zones/{zone_index}/repeat	Get zone repeat mode	—	RepeatMode
PUT	/api/v1/zones/{zone_index}/repeat	Set zone repeat mode	RepeatMode	—
POST	/api/v1/zones/{zone_index}/repeat/toggle	Toggle zone repeat mode	—	—
GET	/api/v1/zones/{zone_index}/shuffle	Get zone shuffle status	—	boolean
PUT	/api/v1/zones/{zone_index}/shuffle	Set zone shuffle status	boolean	—
POST	/api/v1/zones/{zone_index}/shuffle/toggle	Toggle zone shuffle status	—	—
POST	/api/v1/zones/{zone_index}/stop	Stop zone playback	—	—
GET	/api/v1/zones/{zone_index}/track	Get active track index	—	integer
GET	/api/v1/zones/{zone_index}/track/album	Get active track album	—	string
GET	/api/v1/zones/{zone_index}/track/artist	Get active track artist	—	string
GET	/api/v1/zones/{zone_index}/track/duration	Get active track duration	—	integer
GET	/api/v1/zones/{zone_index}/track/metadata	Get track metadata	—	ZoneTrackMetadata
GET	/api/v1/zones/{zone_index}/track/playing	Get track playing state	—	boolean
GET	/api/v1/zones/{zone_index}/track/position	Get active track playback position	—	integer
PUT	/api/v1/zones/{zone_index}/track/position	Seek track position	SeekPayload	—
GET	/api/v1/zones/{zone_index}/track/progress	Get track progress percentage	—	number
PUT	/api/v1/zones/{zone_index}/track/progress	Seek track progress percentage	number	—
GET	/api/v1/zones/{zone_index}/track/title	Get active track title	—	string
GET	/api/v1/zones/{zone_index}/volume	Get zone volume level	—	integer
PUT	/api/v1/zones/{zone_index}/volume	Set zone volume level	VolumeValue	integer

clients

Individual speaker volume, mute, latency, and zone assignment

Method	Endpoint	Summary	Request	Success response
GET	/api/v1/clients	Get all clients details	—	array<ClientInfo>
GET	/api/v1/clients/count	Get total number of clients	—	integer
GET	/api/v1/clients/{client_index}	Get client details by index	—	ClientInfo
GET	/api/v1/clients/{client_index}/connected	Get client connection status	—	boolean
GET	/api/v1/clients/{client_index}/icon	Get client icon name	—	string
GET	/api/v1/clients/{client_index}/latency	Get client latency setting	—	integer
PUT	/api/v1/clients/{client_index}/latency	Set client latency setting	integer	integer
GET	/api/v1/clients/{client_index}/mute	Get client mute status	—	boolean
PUT	/api/v1/clients/{client_index}/mute	Set client mute status	boolean	boolean
POST	/api/v1/clients/{client_index}/mute/toggle	Toggle client mute status	—	boolean
GET	/api/v1/clients/{client_index}/name	Get client friendly name	—	string
PUT	/api/v1/clients/{client_index}/name	Set client friendly name	string	string
GET	/api/v1/clients/{client_index}/volume	Get client volume level	—	integer
PUT	/api/v1/clients/{client_index}/volume	Set client volume level	VolumeValue	integer
GET	/api/v1/clients/{client_index}/zone	Get client zone assignment	—	integer
PUT	/api/v1/clients/{client_index}/zone	Set client zone assignment	integer	integer

equalizer

Parametric EQ curves, bands, and presets for zones and clients

Method	Endpoint	Summary	Request	Success response
GET	/api/v1/clients/{client_index}/eq	Get client Equalizer configuration	—	EqConfig
PUT	/api/v1/clients/{client_index}/eq	Set client Equalizer configuration	EqConfig	EqConfig
POST	/api/v1/clients/{client_index}/eq/preset	Apply client Equalizer preset	string	EqConfig
PUT	/api/v1/clients/{client_index}/eq/{band_index}	Update specific client Equalizer band	EqBand	EqConfig
GET	/api/v1/eq/presets	List EQ presets	—	array<EqPreset>
GET	/api/v1/zones/{zone_index}/eq	Get zone Equalizer configuration	—	EqConfig
PUT	/api/v1/zones/{zone_index}/eq	Set zone Equalizer configuration	EqConfig	EqConfig
POST	/api/v1/zones/{zone_index}/eq/preset	Apply Equalizer preset	string	EqConfig
PUT	/api/v1/zones/{zone_index}/eq/{band_index}	Update specific Equalizer band	EqBand	EqConfig

speakers

Speaker profiles database and correction applications

Method	Endpoint	Summary	Request	Success response
GET	/api/v1/clients/{client_index}/speaker	Get client speaker correction	—	EqConfig
PUT	/api/v1/clients/{client_index}/speaker	Apply speaker correction profile	ApplySpeakerRequest	EqConfig
GET	/api/v1/speakers	List available speaker profiles	—	array<string>
GET	/api/v1/speakers/{name}/profile	Get speaker correction profile	—	EqConfig

knx

KNX home automation integration status and control

Method	Endpoint	Summary	Request	Success response
GET	/api/v1/knx/knxprod	Download the KNX ETS product database	—	—
GET	/api/v1/knx/product-info	Product identity (version / order number / hardware revision) of the embedded .knxprod.	—	ProductInfo
GET	/api/v1/knx/programming-mode	Get KNX programming mode status	—	boolean
PUT	/api/v1/knx/programming-mode	Set KNX programming mode status	boolean	boolean

media

Radio station lists, Subsonic playlists, track listings, and covers

Method	Endpoint	Summary	Request	Success response
GET	/api/v1/media/cover/{cover_id}	Get a cover image by its Subsonic cover id	—	—
GET	/api/v1/media/playlists	Get all media playlists	—	array<PlaylistInfo>
POST	/api/v1/media/playlists	Create a Subsonic playlist	CreatePlaylist	PlaylistInfo
GET	/api/v1/media/playlists/by-id/{playlist_id}	Get playlist details by playlist_id	—	PlaylistDetails
DELETE	/api/v1/media/playlists/by-id/{playlist_id}	Delete a Subsonic playlist	—	—
PATCH	/api/v1/media/playlists/by-id/{playlist_id}	Change a Subsonic playlist	PatchPlaylist	PlaylistDetails
GET	/api/v1/media/playlists/by-id/{playlist_id}/tracks	Get playlist tracks by playlist_id	—	array<MediaTrackInfo>
PUT	/api/v1/media/playlists/by-id/{playlist_id}/tracks	Replace the tracks of a Subsonic playlist	ReplaceTracks	PlaylistDetails
GET	/api/v1/media/playlists/{playlist_index}	Get playlist details	—	PlaylistDetails
GET	/api/v1/media/playlists/{playlist_index}/cover	Get playlist cover image	—	—
GET	/api/v1/media/playlists/{playlist_index}/tracks	Get playlist tracks	—	array<MediaTrackInfo>
GET	/api/v1/media/playlists/{playlist_index}/tracks/{track_index}	Get track details	—	MediaTrackInfo
GET	/api/v1/media/playlists/{playlist_index}/tracks/{track_index}/cover	Get track cover image	—	—
GET	/api/v1/media/search	Search the music library, the playlists and the radio stations	—	SearchResponse

Schemas

ApplySpeakerRequest

Request body for applying a speaker correction.

Field	Type	Required	Description
custom	EqConfig or null	no	—
speaker	string or null	no	Speaker name (from spinorama). Mutually exclusive with custom.

BindSupport

How far a service honours a bind setting.

Type: full, partial, none

ClientInfo

Field	Type	Required	Description
connected	boolean	yes	—
icon	string	yes	—
index	integer	yes	—
is_snapdog	boolean	yes	—
mac	string	yes	—
max_volume	integer	yes	—
muted	boolean	yes	—
name	string	yes	—
volume	integer	yes	—
zone_index	integer	yes	—

CreatePlaylist

Body of POST /media/playlists.

Field	Type	Required	Description
name	string	yes	Name of the new playlist.
track_ids	array<string>	no	Subsonic track ids to start with, in order.

EqBand

Single EQ band configuration.

Field	Type	Required	Description
freq	number	yes	Center frequency in Hz.
gain	number	yes	Gain in dB (positive = boost, negative = cut). Ignored for low/high pass.
q	number	yes	Q factor controlling bandwidth. Higher values = narrower band.
type	FilterType	yes	Filter type (low shelf, high shelf, peaking, low pass, high pass).

EqConfig

Full EQ configuration for a zone.

Field	Type	Required	Description
bands	array<EqBand>	yes	Ordered list of biquad filter bands applied in series.
enabled	boolean	yes	Whether the EQ is active. When false, audio passes through unmodified.
preset	string or null	no	Name of the preset this config was loaded from, if any.

EqPreset

A named EQ preset with the bands it applies.

Field	Type	Required	Description
bands	array<EqBand>	yes	Bands the preset sets. Empty for flat.
name	string	yes	Preset name, as accepted by the eq/preset calls of zones and clients.

ErrorBody

Standard REST API error response body.

Field	Type	Required	Description
error	string	yes	High-level machine-readable error classification.
message	string	yes	Detailed human-readable explanation of the error.

FilterType

Filter type for an EQ band.

Type: low_shelf, high_shelf, peaking, low_pass, high_pass

MediaTrackInfo

Field	Type	Required	Description
album	string	yes	—
artist	string	yes	—
cover_art	string or null	no	—
duration	integer	yes	—
id	string	yes	—
title	string	yes	—
track	integer	yes	—

PatchPlaylist

Body of PATCH /media/playlists/by-id/{playlist_id}: the three operations of updatePlaylist.

Field	Type	Required	Description
add_track_ids	array<string>	no	Subsonic track ids appended to the end.
name	string or null	no	New name.
remove_positions	array<integer>	no	Positions (0-based, in the playlist as it is now) of tracks to remove.

PlaybackControl

Playback control command sent from client to server.

Type: object or object or object or object or object or object or object or object or object or object or object

PlaylistByIdPayload

Body of POST /zones/{zone_index}/play/playlist/by-id.

Field	Type	Required	Description
playlist_id	string	yes	Stable playlist reference (snapdog:radio, subsonic:<id>).
track	integer	no	Track index to start at (0-based, default 0).

PlaylistDetails

Field	Type	Required	Description
id	integer	yes	Unified playlist index. Deprecated. Use index. Removed with SnapDog 1.0, which breaks compatibility of /api/v1 for clients that still read it.
index	integer	yes	Unified playlist index (0-based). Moves when the list changes, see playlist_id.
name	string	yes	—
playlist_id	string	yes	Stable reference: snapdog:radio or subsonic:<subsonic id>.
tracks	integer	yes	—

PlaylistInfo

Field	Type	Required	Description
cover_art	string or null	no	—
duration	integer	yes	—
id	integer	yes	Unified playlist index. Deprecated. Use index. Removed with SnapDog 1.0, which breaks compatibility of /api/v1 for clients that still read it.
index	integer	yes	Unified playlist index (0-based). Moves when the list changes, see playlist_id.
name	string	yes	—
playlist_id	string	yes	Stable reference: snapdog:radio or subsonic:<subsonic id>.
song_count	integer	yes	—

PlaylistPayload

Field	Type	Required	Description
id	integer or null	no	Unified playlist index. Deprecated. Use index. Removed with SnapDog 1.0, which breaks compatibility of /api/v1 for clients that still read it.
index	integer or null	no	Unified playlist index (0-based).
track	integer	no	—

ProductInfo

ETS product identity of the embedded .knxprod, shown next to the WebUI download so an integrator can confirm it matches this device’s firmware.

Field	Type	Required	Description
app_version	integer	yes	ETS ApplicationVersion.
application_number	string	yes	ApplicationNumber / order number, formatted 0xFF01.
hardware_version	integer	yes	Hardware revision.

Protocol

Transport protocol of a listener.

Type: tcp, udp

RepeatMode

Repeat mode for zone playback.

Type: off, track, playlist

ReplaceTracks

Body of PUT /media/playlists/by-id/{playlist_id}/tracks.

Field	Type	Required	Description
track_ids	array<string>	yes	The complete new content, in order.

Row

One line of the listener table: a listener, and what an operator needs to know about binding it.

Field	Type	Required	Description
address	string	yes	Address, 0.0.0.0 or :: for every interface of that family.
backend	string	yes	What creates the socket.
bind_support	BindSupport	yes	Whether a bind setting reaches this socket.
note	string	yes	What the bind support level means for this service, in one sentence.
port	integer	yes	Port. 0 means a random port at every start.
protocol	Protocol	yes	Transport protocol.
service	string	yes	Service that owns the listener.
via	string or null	no	The bind entry this address came from when that was an interface name or loopback, for example eth0. Absent when the address was written as an address or is the default.

SearchItem

One search result. The identifier has a field per kind, there is no generic one.

Field	Type	Required	Description
album_id	string or null	no	Subsonic album id (kind album). Plays with POST /zones/{zone}/play/subsonic/album/{album_id}.
cover_art	string or null	no	Path of a cover image, see GET /media/cover/{cover_id}.
duration	integer	yes	Seconds, 0 if unknown.
index	integer or null	no	Current unified index of the playlist (kinds playlist and radio).
kind	string	yes	track, album, playlist or radio.
playlist_id	string or null	no	Stable reference (kinds playlist and radio, where radio is the list snapdog:radio).
subtitle	string or null	no	Artist, or album for a track. Absent for a playlist.
title	string	yes	—
track	integer or null	no	Position of the station in the radio list (kind radio), the track to play it with.
track_id	string or null	no	Subsonic track id (kind track). Plays with POST /zones/{zone}/play/subsonic/{track_id}.

SearchResponse

Body of GET /media/search.

Field	Type	Required	Description
items	array<SearchItem>	yes	—
next_offset	integer or null	no	Offset of the next page, null when no kind filled its page.

SeekPayload

Field	Type	Required	Description
offset_ms	integer or null	no	—
position_ms	integer or null	no	—

SystemStatus

Field	Type	Required	Description
clients	integer	yes	—
radios	integer	yes	—
version	string	yes	—
zones	integer	yes	—

TrackMetadata

Full zone state pushed from server to client via custom message.

Field	Type	Required	Description
album	string	yes	Album name.
album_artist	string or null	no	Album artist (may differ from track artist).
artist	string	yes	Track artist.
bitrate_kbps	integer or null	no	Audio bitrate in kbps.
can_next	boolean	yes	Whether next track is available.
can_playlist_next	boolean	yes	Whether there’s a next playlist.
can_playlist_prev	boolean	yes	Whether there’s a previous playlist.
can_prev	boolean	yes	Whether previous track is available.
content_type	string or null	no	MIME content type.
cover_url	string or null	no	Absolute cover art URL.
disc_number	integer or null	no	Disc number.
duration_ms	integer	yes	Total track duration in milliseconds.
genre	string or null	no	Genre tag.
muted	boolean	yes	Whether the zone is muted.
playback	string	yes	Playback state: “playing”, “paused”, “stopped”.
playlist	integer or null	no	Current playlist index (0-based).
playlist_name	string or null	no	Name of the active playlist.
playlist_total	integer or null	no	Total number of playlists available.
position_ms	integer	yes	Current playback position in milliseconds.
repeat	RepeatMode	yes	Repeat mode.
seekable	boolean	yes	Whether seeking is supported.
shuffle	boolean	yes	Whether shuffle is enabled.
source	string	yes	Active source type.
title	string	yes	Track title.
track_count	integer or null	no	Total tracks in playlist.
track_index	integer or null	no	Current track index in playlist (0-based).
track_number	integer or null	no	Track number within the album.
volume	integer	yes	Zone volume (0–100).
year	integer or null	no	Release year.

UpdateConfig

New update schedule for the container updater sidecar.

Field	Type	Required	Description
maintenanceTime	string	yes	Local time of day for automatic updates, HH:MM.
mode	string	yes	manual only checks and applies when asked, automatic applies new releases at maintenanceTime.
timezone	string	yes	IANA time zone the maintenance time is read in.

UpdateProgress

Progress of a running update.

Field	Type	Required	Description
detail	string or null	no	Further detail about the phase, if any.
phase	string	yes	Current phase of the update.

UpdateStatus

State of the container updater sidecar, as reported by the sidecar itself. The sidecar may add further fields; the ones listed here are what the WebUI reads.

Field	Type	Required	Description
availableVersion	string or null	no	Newest release found by the last check, if any.
currentVersion	string or null	no	Version of the running image, if known.
lastError	string or null	no	Error of the last check or update, if it failed.
maintenanceTime	string	yes	Local time of day for automatic updates, HH:MM.
progress	UpdateProgress or null	no	—
state	string	yes	Updater state, for example idle, checking, updating.
timezone	string	yes	IANA time zone for maintenanceTime.
updateAvailable	boolean	yes	Whether availableVersion is newer than currentVersion.
updateMode	string	yes	manual or automatic.

VersionInfo

Field	Type	Required	Description
name	string	yes	—
rust_version	string	yes	—
version	string	yes	—

VolumeValue

Volume value: absolute (e.g. 75) or relative (e.g. "+5", "-3").

Type: integer or string

ZoneInfo

Field	Type	Required	Description
icon	string	yes	—
index	integer	yes	—
muted	boolean	yes	—
name	string	yes	—
playback	string	yes	—
presence	boolean	yes	—
presence_enabled	boolean	yes	—
presence_timer_active	boolean	yes	—
repeat	RepeatMode	yes	—
shuffle	boolean	yes	—
source	string	yes	—
volume	integer	yes	—

ZonePlaylistInfo

Field	Type	Required	Description
index	integer or null	no	—
name	string or null	no	—
playlist_id	string or null	no	Stable reference of the active playlist (snapdog:radio, subsonic:<id>).
total	integer or null	no	—
track_count	integer or null	no	—
track_index	integer or null	no	—

ZoneTrackMetadata

Field	Type	Required	Description
album	string	yes	—
album_artist	string or null	no	—
artist	string	yes	—
bitrate_kbps	integer or null	no	—
can_next	boolean	yes	—
can_playlist_next	boolean	yes	—
can_playlist_prev	boolean	yes	—
can_prev	boolean	yes	—
content_type	string or null	no	—
cover_url	string or null	no	—
disc_number	integer or null	no	—
duration_ms	integer	yes	—
genre	string or null	no	—
playlist_id	string or null	no	Stable reference of the active playlist (snapdog:radio, subsonic:<id>).
playlist_index	integer or null	no	—
playlist_name	string or null	no	—
playlist_total	integer or null	no	—
playlist_track_count	integer or null	no	—
playlist_track_index	integer or null	no	—
position_ms	integer	yes	—
sample_rate	integer or null	no	—
seekable	boolean	yes	—
source	string	yes	—
title	string	yes	—
track_number	integer or null	no	—
year	integer or null	no	—