Skip to content
On this page

Synara API Constants

Guides: API_VERSIONING.md · AUTHENTICATION.md · Index: README.md

API version

Constant Value
ApiVersion.HEADER X-Api-Version
ApiVersion.LEGACY 1
ApiVersion.CURRENT 11

Features

Version Feature Introduces Older clients get Max version
2 LOSSLESS_WAV_AIFF Streaming WAV and AIFF source files as they are. The server transcodes the file to FLAC before streaming it. -
3 DOLBY_ATMOS The Dolby Atmos variant of a song (E-AC-3 JOC in MP4) and the streamSongAtmos endpoint. The Atmos stream resolves to nothing — there is no Atmos playback. Songs still carry atmos. -
4 AUDIO_INFO File properties nested in audio and atmos as AudioInfo — codec, sampleRate, bitsPerSample, bitRate, fileSize, channels. There is no fallback. The flat top-level fields are gone, so clients below this version get no file properties. -
5 SERVER_DRIVEN_UI Component trees from the server, rendered natively by the client. Nothing to render. The companion X-Ui-Schema-Version header controls the detail. -
6 TITLE_TAGS tags: version markers such as Radio Edit, feat. Drake or Live at Wembley, split off the title into TitleTag entries, so title is clean. title is put back together into the full original title and tags is emptied. -
7 RELEASE_VERSIONS versions on RecentRelease: the editions of one release (explicit, deluxe, remastered, or the same release from another catalog) are folded under a single feed entry. Every edition is its own feed entry, following the entry it was folded into, and versions is empty. -
8 FIELD_RENAMES Renamed fields under their new names: musicBrainzId on Album, Artist and ArtistCredit, isPlaying on PlaybackReport, directMember on CollectionSongMatch and RadioChannelSongMatch, isShuffled on PlaybackState, QueueInfo, QueueMeta and RemotePlaybackStatus, and userAdded on QueueItem. The queue entry with full song metadata has the type WithSong. There is no fallback. The old names are no longer served, so clients below this version cannot read or send these fields. -
9 ALBUM_TITLE_TAGS tags on Album: edition markers such as Deluxe Edition, 10th Anniversary or 2011 Remaster, split off the album name into TitleTag entries, so name is clean. name is put back together into the full original name and tags is emptied. -
9 ALBUM_VERSIONS versions on Album: the editions of one album (deluxe, anniversary, remastered, explicit or clean) are folded under a single entry in the album lists. Every edition is its own entry, following the entry it was folded into, and versions is empty. -
10 ENTITY_CHANGES The IEntityChangeService service, which answers what changed in the library since a time the client names. There is none, a client reads everything again. -
11 LYRICS_SERVICE lyricsInfo on Song and UserSong. The lyrics field is gone, lyrics are read through ILyricsCandidateService. Songs carry lyrics with the stored plain or line-synced text and no lyricsInfo. -

UI schema version

Constant Value
UiSchemaVersion.HEADER X-Ui-Schema-Version
UiSchemaVersion.NONE 0
UiSchemaVersion.CURRENT 3
ClientTimeZone.HEADER X-Time-Zone
Component Introduced in
badge 1
button 1
card 1
column 1
divider 1
emptyState 1
fallback 1
form 1
grid 1
icon 1
image 1
listItem 1
live 1
log 1
native 1
numberField 1
progress 1
row 1
section 1
select 1
spacer 1
stat 1
switch 1
table 1
text 1
textField 1
tile 1
fileField 2
searchField 3

Authentication

Constant Value
Access token lifetime 24h
Refresh token lifetime 30d
JWT claim for username usr
JWT claim for session id ses
Cookie name synara-auth
API key query parameter apiKey
API key header X-API-Key

API key scopes

Scope Name Description Registered by
mcp MCP Read-only Model Context Protocol access to listen history and listening statistics. server
radio Radio streaming Stream radio channels. server
subsonic Subsonic API Authenticate Subsonic/OpenSubsonic clients via the apiKey parameter. subsonic