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/status	Retrieve basic system status statistics.	—	SystemStatus
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/{playlist_index}/track	Play track in a playlist	integer	—
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/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/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/playlists	Get all media playlists	—	array<PlaylistInfo>
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	—	—

Schemas

ApplySpeakerRequest

Request body for applying a speaker correction.

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

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	—

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.

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	—

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

PlaylistDetails

Field	Type	Required	Description
id	integer	yes	—
name	string	yes	—
tracks	integer	yes	—

PlaylistInfo

Field	Type	Required	Description
cover_art	string or null	no	—
duration	integer	yes	—
id	integer	yes	—
name	string	yes	—
song_count	integer	yes	—

PlaylistPayload

Field	Type	Required	Description
id	integer	yes	—
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.

RepeatMode

Repeat mode for zone playback.

Type: off, track, playlist

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.

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	—
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_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	—