Skip to content
Synara
Synara
On this page

Synara REST API

Services: RPC_SERVICES.md · Models: MODELS.md · Guide: CLIENT_REST.md · Index: README.md

How to read this file

  • Every route is derived from an RPC interface function; the derivation rules (method, path segment, parameter binding) are listed in How routes are derived below and explained with examples in CLIENT_REST.md.
  • Parameters lists each parameter with its binding: path (a path segment), query (a query parameter; collections repeat the name= pair, objects on GET are JSON-encoded) or body (JSON; when a route has several body parameters the request body is one JSON object with one field per parameter). optional marks a parameter that has a default or is nullable, and the text after the colon is its documentation.
  • Response is JSON <type> (a JSON body), SSE <item type> (Server-Sent Events, one JSON object per data: line), FILE (served on GET and HEAD with Accept-Ranges: bytes and Content-Disposition: inline), BYTES (a raw binary body) or - (an empty 200).
  • Auth is public (no token needed), JWT (an Authorization: Bearer <token> header or the synara-auth cookie), JWT + Admin or JWT + <CAPABILITY> for a required user capability.
  • The serverStats, auth, handshake services are mounted without requiring a user, so all of their routes are reachable without a token and are listed as public here.
  • Errors are returned as a plain-text body with status 400, 401, 403, 404 or 500.

How routes are derived

Nothing on this page is written by hand: every route below is derived from one function of an RPC service interface by the same rules the server's routing code is generated with.

Service prefix. The interface name without a leading I and a trailing Service, with the first letter lowercased: ISongService is mounted at /song, IPodcastService at /podcast.

Verb and path segment. They follow the function name. The first matching rule wins, and a prefix only matches as a whole word — the character after it must be an upper-case letter or a digit, or the name must be exactly the prefix. The segment keeps the name with its first letter lowercased.

Method name starts with Verb Segment
by GET the whole name
all GET the whole name
liked GET the whole name
stream GET the whole name
import GET the whole name
download GET the whole name
get GET the name without the prefix
list GET the name without the prefix
find GET the name without the prefix
fetch GET the name without the prefix
search GET the name without the prefix
ranked GET the name without the prefix
exists GET the whole name
anything containing Exists GET the whole name
add POST the whole name
post POST the name without the prefix
create POST the name without the prefix
put PUT the name without the prefix
set PUT the name without the prefix
update PUT the name without the prefix
delete DELETE the name without the prefix
remove DELETE the name without the prefix
anything else POST the whole name

Explicit overrides. @RestGet, @RestPost, @RestPut and @RestDelete on the function replace the derived verb; @RestPath("segment") replaces the derived segment.

Path parameters. A parameter named type that is primitive, not nullable and has no default becomes a leading {type} segment. The first parameter named id or ending in Id that is primitive, not nullable and has no default becomes a trailing {name} segment. Every other parameter binds by its type and the route's verb.

Parameter Bound as
a path parameter (type or the id, see above) a path segment
a primitive a query parameter
a List or Set of primitives repeated query values (name=a&name=b; one comma-separated value is also accepted)
a non-primitive on a GET route a JSON-encoded query value
a non-primitive on a POST, PUT or DELETE route the JSON request body
several body parameters one JSON object with one field per parameter

Response. The return type decides how the body is written.

Return type Response
Flow<ByteArray> a byte stream
anything annotated @RestFileResponse served on GET and HEAD with Accept-Ranges: bytes
another Flow<T> SSE, one JSON item per data: line
ByteArray raw bytes
Unit an empty 200
anything else a JSON body

Table of Contents

/indexer — IIndexer

Local file system media scanning.

RPC reference: IIndexer

Method Path Parameters Response Auth Description
POST /indexer/start - SSE String JWT + Admin Start indexing files in the media library and stream progress updates. (start)

/album — IAlbumService

Manages albums and their metadata.

RPC reference: IAlbumService

Method Path Parameters Response Auth Description
PUT /album/album album (body, Album): The album object with updated fields. JSON Album? JWT + EDIT Update album metadata. (updateAlbum)
DELETE /album/albums ids (query, repeated, List<PlatformUUID>): Collection of album IDs to delete. JSON Boolean JWT + DELETE Delete multiple albums from the library. (deleteAlbums)
GET /album/allAlbums page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
explicit (query, Boolean?, optional): True prefers the explicit edition as the main one when an album exists in an explicit and a clean edition. False prefers the clean one. When it is not given, the explicit edition is preferred.		 JSON PaginatedResponse<Album> JWT Get all albums in the library, grouped into editions. Each entry is the main edition of an album and carries the other editions in versions. (allAlbums)
GET /album/byArtist/{artistId} page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
artistId (path, PlatformUUID): The artist unique identifier.
singles (query, Boolean, optional): Whether to include singles.
explicit (query, Boolean?, optional): True prefers the explicit edition as the main one when an album exists in an explicit and a clean edition. False prefers the clean one. When it is not given, the explicit edition is preferred.		 JSON PaginatedResponse<Album> JWT List albums by artist, grouped into editions. Each entry is the main edition of an album and carries the other editions in versions. (byArtist)
GET /album/byColor page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
color (query, Int): The target color in ARGB format.
range (query, Int, optional): The allowed range (0-255).		 JSON PaginatedResponse<Album> JWT Search for albums by color. (byColor)
GET /album/byId/{id} id (path, PlatformUUID): The album unique identifier. JSON Album? JWT Get album by ID. (byId)
GET /album/byIds ids (query, repeated, List<PlatformUUID>): Collection of album IDs. JSON List<Album> JWT Get multiple albums by their IDs. (byIds)
GET /album/byMusicBrainzId/{mbId} mbId (path, PlatformUUID): The MusicBrainz release (or release-group) UUID. JSON List<Album> JWT Get album by MusicBrainz ID. (byMusicBrainzId)
GET /album/byMusicBrainzIds mbIds (query, repeated, List<PlatformUUID>): Collection of MusicBrainz release (or release-group) UUIDs. JSON List<Album?> JWT Get multiple albums by their MusicBrainz IDs. (byMusicBrainzIds)
GET /album/byName page (query, Int, optional): Page index (starting from 0).
pageSize (query, Int, optional): Number of items per page.
name (query, String): The album name to search for.		 JSON PaginatedResponse<Album> JWT Search albums by name. (byName)
GET /album/byOriginalIds ids (query, repeated, Collection<PrefixedId>): Collection of original platform-specific album identifiers. JSON List<Album> JWT Find albums by their original platform-specific unique identifiers. (byOriginalIds)
GET /album/byOriginalUrls urls (query, repeated, Collection<String>): Collection of original platform URLs. JSON Map<String, Album?> JWT Find albums by their original platform URLs, returning a mapping. (byOriginalUrls)
GET /album/byVersionGroup/{versionGroupId} versionGroupId (path, PlatformUUID): The version group unique identifier, as carried by versionGroupId on an album.
explicit (query, Boolean, optional): True prefers the explicit edition as the main one when an album exists in an explicit and a clean edition. False prefers the clean one.		 JSON List<Album> JWT List all albums of a version group, main edition first. The albums come back as a flat list and their versions lists are empty. (byVersionGroup)
GET /album/extendedMetadata/{id} id (path, PlatformUUID): The album unique identifier. JSON AlbumExtendedMetadata? JWT Get extended metadata for an album. (extendedMetadata)
POST /album/musicBrainzId/{id} id (path, PlatformUUID): The album unique identifier. JSON Album? JWT + EDIT Fetch and link MusicBrainz ID for an album. (fetchMusicBrainzId)
PUT /album/musicBrainzId/{id} id (path, PlatformUUID): The album unique identifier.
musicBrainzId (query, PlatformUUID?, optional): The MusicBrainz Release UUID.		 JSON Album? JWT + EDIT Manually set MusicBrainz ID for an album. (setMusicBrainzId)
GET /album/search page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
query (query, String): The search query.		 JSON PaginatedResponse<Album> JWT Ranked album search. (rankedSearch)
GET /album/versions/{id} id (path, PlatformUUID): The album unique identifier. JSON List<Album> JWT List the other editions of an album, main edition first. (versions)

/animatedImage — IAnimatedImageService

Management of animated cover files (short looping videos).

RPC reference: IAnimatedImageService

Method Path Parameters Response Auth Description
POST /animatedImage/animatedImage bytes (body, ByteArray): The raw binary data of the animated image.
origin (query, String, optional): The source or category of the animated image.		 JSON PlatformUUID JWT Store a new animated image on the server. (createAnimatedImage)
POST /animatedImage/batch images (body, List<InsertableAnimatedImage>): Collection of animated images to store. JSON Map<String, PlatformUUID> JWT Store multiple animated images on the server in a single operation. (createBatch)
GET /animatedImage/byHash hash (query, String): The unique hash of the animated image. JSON AnimatedImage? JWT Find animated image metadata by its content hash. (byHash)
GET /animatedImage/byId/{id} id (path, PlatformUUID): The animated image unique identifier. JSON AnimatedImage? JWT Get animated image metadata by its unique ID. (byId)
GET /animatedImage/coverHashes hashes (query, repeated, List<String>): Collection of animated image hashes. JSON Map<String, PlatformUUID> JWT Map a list of animated image hashes to their existing internal UUIDs. (getCoverHashes)
GET /animatedImage/imageData/{id} id (path, PlatformUUID): The animated image unique identifier. BYTES public Retrieve the raw binary data of an animated image. (getAnimatedImageData)

/apiKey — IApiKeyService

Manages long-lived API keys for authenticating non-interactive clients (e.g. media players).

RPC reference: IApiKeyService

Method Path Parameters Response Auth Description
POST /apiKey/apiKey label (query, String): Human-readable label describing where the key will be used.
scopes (query, repeated, List<String>): Identifiers of the scopes to grant to the key. Must be registered scopes.		 JSON String JWT Create a new API key and return the raw secret. (createApiKey)
GET /apiKey/apiKeyString/{id} id (path, PlatformUUID): The API key unique identifier. JSON String? JWT Get the raw secret of one of the current user's API keys. Returns null for keys created before secrets were stored. (getApiKeyString)
GET /apiKey/apiKeys - JSON List<ApiKeyInfo> JWT List metadata for all API keys belonging to the current user. Never returns the secrets. (listApiKeys)
GET /apiKey/availableScopes - JSON List<ApiKeyScopeInfo> JWT List all scopes that can be granted to API keys. (listAvailableScopes)
POST /apiKey/revokeApiKey/{id} id (path, PlatformUUID): The API key unique identifier. JSON Boolean JWT Revoke an API key by its identifier. Returns true if a key was revoked. (revokeApiKey)

/artist — IArtistService

Manages artist data and complex library maintenance.

RPC reference: IArtistService

Method Path Parameters Response Auth Description
DELETE /artist/alias/{artistId} artistId (path, PlatformUUID): The artist unique identifier.
name (query, String): The alternative name.		 JSON Boolean JWT + EDIT Remove an alias from an artist. (removeAlias)
POST /artist/alias/{artistId} artistId (path, PlatformUUID): The artist unique identifier.
name (query, String): The alternative name.		 JSON Boolean JWT + EDIT Add an alias to an artist. (addAlias)
GET /artist/aliases/{id} id (path, PlatformUUID): The artist unique identifier. JSON List<ArtistAlias> JWT List aliases for an artist. (aliases)
GET /artist/allArtists page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.		 JSON PaginatedResponse<Artist> JWT Get all artists in the library, ordered by name without regard to case, artists with the same name by ID. (allArtists)
POST /artist/artist name (query, String): Name of the artist.
isGroup (query, Boolean, optional): Whether the artist is a group.
about (query, String, optional): Optional biography or description.
musicBrainzId (query, PlatformUUID?, optional): Optional MusicBrainz ID.		 JSON Artist JWT + EDIT Manually create an artist record. (createArtist)
GET /artist/artistIdsWithoutMusicBrainzId - SSE PlatformUUID JWT Stream IDs of all artists that are missing a MusicBrainz ID. (artistIdsWithoutMusicBrainzId)
PUT /artist/artistImageByUrl/{id} id (path, PlatformUUID): The artist unique identifier.
url (query, String): The direct image URL.		 JSON Artist? JWT + EDIT Set an artist's image from a direct URL. (setArtistImageByUrl)
GET /artist/artistOnMusicBrainz query (query, String): The search query.
page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.		 JSON PaginatedResponse<MusicBrainzArtist> JWT Search for an artist directly on MusicBrainz. (searchArtistOnMusicBrainz)
GET /artist/artistsWithoutMusicBrainzId - SSE Artist JWT Stream all artists that are missing a MusicBrainz ID. (artistsWithoutMusicBrainzId)
GET /artist/byColor page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
color (query, Int): The target color in ARGB format.
range (query, Int, optional): The allowed range (0-255).		 JSON PaginatedResponse<Artist> JWT Search for artists by color. (byColor)
GET /artist/byGroup/{groupId} page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
groupId (path, PlatformUUID): The group artist unique identifier.		 JSON PaginatedResponse<Artist> JWT List artists in a group, ordered by name without regard to case, artists with the same name by ID. (byGroup)
GET /artist/byId/{id} id (path, PlatformUUID): The artist unique identifier. JSON Artist? JWT Get artist by ID. (byId)
GET /artist/byIds ids (query, repeated, List<PlatformUUID>): Collection of artist IDs. JSON List<Artist> JWT Get multiple artists by their IDs. (byIds)
GET /artist/byMusicBrainzId/{mbId} mbId (path, PlatformUUID): The MusicBrainz artist UUID. JSON List<Artist> JWT Get artist by MusicBrainz ID. (byMusicBrainzId)
PUT /artist/group/{id} id (path, PlatformUUID): The group artist unique identifier.
artistIds (query, repeated, List<PlatformUUID>?, optional): Optional collection of sub-artist IDs.		 JSON Artist? JWT + EDIT Set sub-artists for a group. (setGroup)
POST /artist/mergeArtists mergeArtists (body, MergeArtists): Configuration for merging artists. JSON Artist? JWT + EDIT Merge multiple artist records into one. (mergeArtists)
POST /artist/musicBrainzId/{id} id (path, PlatformUUID): The artist unique identifier. JSON Artist? JWT + EDIT Fetch and link MusicBrainz ID for an artist. (fetchMusicBrainzId)
PUT /artist/musicBrainzId/{id} id (path, PlatformUUID): The artist unique identifier.
musicBrainzId (query, PlatformUUID?, optional): The MusicBrainz ID to link.		 JSON Artist? JWT + EDIT Link an artist record to a MusicBrainz ID. (setMusicBrainzId)
GET /artist/search page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
query (query, String): The search query.		 JSON PaginatedResponse<Artist> JWT Ranked artist search. (rankedSearch)
POST /artist/splitArtist splitArtist (body, SplitArtist): Configuration for splitting an artist. JSON List<Artist> JWT + EDIT Split an artist record into multiple artists. (splitArtist)
GET /artist/topSongs/{artistId} artistId (path, PlatformUUID): The artist unique identifier.
limit (query, Int, optional): Maximum number of songs. Clamped to 1..100.
order (query, ArtistTopSongOrder, optional): How the songs are ranked.		 JSON List<ArtistTopSong> JWT List the artist's library songs ranked by popularity. The list holds the artist's most listened songs across all listeners and the artist's songs the current user has listened to. (topSongs)
GET /artist/{type}/artistImages type (path, MetadataType): The metadata provider to use.
query (query, String): The artist name to search for.
limit (query, Int, optional): Maximum number of images to return.		 JSON List<Image> JWT Search for artist images using a metadata provider. (searchArtistImages)

/audioAnalysis — IAudioAnalysisService

Service for audio analysis and related data management.

RPC reference: IAudioAnalysisService

Method Path Parameters Response Auth Description
POST /audioAnalysis/analyzeSong/{songId} songId (path, PlatformUUID): The song unique identifier. - JWT Trigger analysis for a song. (analyzeSong)
GET /audioAnalysis/audioData/{songId} songId (path, PlatformUUID): The song unique identifier. JSON SongAudioData? JWT Get audio analysis data for a song. (getAudioData)
GET /audioAnalysis/audioTimeline/{songId} songId (path, PlatformUUID): The song unique identifier. JSON SongAudioTimeline? JWT Get the beat grid and loudness envelope of a song, or null when not extracted yet. Call analyzeSong to extract it. (getAudioTimeline)

/auth — IAuthService

Handles user login and session security.

RPC reference: IAuthService

Method Path Parameters Response Auth Description
POST /auth/authenticate username (query, String): The username of the user.
password (query, String): The password of the user.		 JSON AuthenticationResponse public Logs in a user and returns JWT token. (authenticate)
POST /auth/deviceSession userAgent (query, String): The user agent of the device the session is created for. JSON AuthenticationResponse public Creates a new session for another device (e.g. Apple TV) on behalf of the authenticated user. (createDeviceSession)
POST /auth/refreshToken refreshToken (query, String): The refresh token. JSON AuthenticationResponse public Refreshes an expired access token. (refreshToken)

/backup — IBackupService

System-wide data persistence and disaster recovery.

RPC reference: IBackupService

Method Path Parameters Response Auth Description
DELETE /backup/backup fileName (query, String): The name of the backup file. - JWT + Admin Delete a system backup file from the server. (deleteBackup)
POST /backup/backup - JSON BackupResult JWT + Admin Trigger the creation of a full system backup. (createBackup)
GET /backup/backups - JSON List<BackupInfo> JWT + Admin List all available system backup files. (listBackups)
POST /backup/restoreBackup fileName (query, String): The name of the backup file. - JWT + Admin Restore the entire server state from a backup file. (loadBackup)

/change — IChangeService

Tells a client which parts of the user's state changed, so it reads them again with the regular getters instead of polling or keeping one stream open per screen.

RPC reference: IChangeService

Method Path Parameters Response Auth Description
GET /change/observeChanges - SSE Change JWT Watch the state of the user for changes. The stream stays silent until something changes and then emits the ChangeTopic that changed, which names the getter to call again. Bursts of changes to the same topic within a short window arrive as a single change. Nothing is replayed, so a client reads the current state after every (re)subscribe. (observeChanges)

/chart — IChartService

Charts of popular music.

RPC reference: IChartService

Method Path Parameters Response Auth Description
GET /chart/appleChart country (query, String): Two-letter country code, for example us or de.
kind (query, AppleChartKind): Whether to get the song chart or the album chart.
limit (query, Int, optional): Maximum number of entries. Clamped to 1..100.		 JSON AppleChart JWT Get the current Apple Music chart of the most played songs or albums in a country. Every chart entry is returned, entries that are in the library carry the library song or album. (appleChart)

/clientRequest — IClientRequestService

The connection a client keeps open to the server for the lifetime of the app. It carries the tasks the server asks the calling client to perform, which the client performs through the regular RPC services and reports back so the device that asked for it is unblocked, and it doubles as the presence of the client: a session that connects with a description is listed as an online device of the user, with the cross-device features it offers, for exactly as long as it keeps the stream open.

RPC reference: IClientRequestService

Method Path Parameters Response Auth Description
POST /clientRequest/complete/{requestId} requestId (path, PlatformUUID): The identifier of the request that was handled.
status (query, ClientRequestStatus): Whether the request was performed or declined.		 - JWT Report the outcome of a request to the waiting requester. Only COMPLETED and REJECTED are accepted. The timed out and unreachable outcomes are determined by the server. (complete)
GET /clientRequest/connect description (query, JSON, ClientDescription): How this client is listed on the other devices of the user and what it can do. SSE ClientRequest JWT Watch for requests addressed to the calling session and be listed as an online device of the user while the stream is open. The description is kept only for the duration of the stream, so a client that changes its name or its capabilities subscribes again. Requests that need a capability are only delivered to sessions that connected offering it. (connect)
GET /clientRequest/observeRequests - SSE ClientRequest JWT Watch for requests addressed to the calling session without announcing the device. A session that is not subscribed is reported as unreachable to the requester. (observeRequests)
GET /clientRequest/onlineDevices - JSON List<OnlineDevice> JWT List the devices of the user that are connected right now, newest connection first. Sessions that only observe requests without a description are not listed. (getOnlineDevices)

/clientSettings — IClientSettingsService

Stores the settings of the clients of a user as opaque key/value entries, where the value is an arbitrary JSON document in text form and the server never interprets what a setting means. Entries live either in the synced scope, which is shared by all devices of the user, or in the device scope of a single device, and the client decides per key which one it uses. Each scope carries a monotonically increasing version that every accepted write advances by one, and every entry remembers the version it was written at, so clients detect concurrent changes and can catch up incrementally instead of reading everything again.

RPC reference: IClientSettingsService

Method Path Parameters Response Auth Description
GET /clientSettings/changes scope (query, ClientSettingScope): The scope to read.
sinceVersion (query, Long): The version the client is already up to date with. Entries written at a later version are returned.
device (query, String?, optional): The device to read in the device scope. Required for the device scope and ignored in the synced scope.
limit (query, Int, optional): Maximum number of entries to return.		 JSON ClientSettingsChanges JWT Read the entries a scope changed after a version the client already knows, tombstones included and ordered by the version they were written at. When more entries are available than the page holds, the client asks again with the version of the last entry it received. If tombstones the client never saw were already purged, the result asks for a full resync and the client re-reads the whole scope instead. (getChanges)
DELETE /clientSettings/device/{deviceId} deviceId (path, String): The identifier of the device to forget. - JWT Forget a device together with its device-scoped settings and their history. The synced scope is not touched, so the other devices of the user keep their shared settings. (deleteDevice)
GET /clientSettings/devices - JSON List<ClientDevice> JWT List the devices of the user that stored settings on the server, each with the current version of its device scope. (getDevices)
GET /clientSettings/history scope (query, ClientSettingScope): The scope the key belongs to.
key (query, String): The key to read the previous values of.
device (query, String?, optional): The device to read in the device scope. Required for the device scope and ignored in the synced scope.
limit (query, Int, optional): Maximum number of previous values to return.		 JSON List<ClientSetting> JWT Read the previous values of a single key, newest first. The server keeps a bounded number of superseded values per key, so older values are dropped as new ones are written. (getHistory)
GET /clientSettings/observeSettings - SSE ClientSettingsChange JWT Watch the settings of the user for changes. Every accepted write emits the scope it changed, the version it advanced to and the keys it touched, including writes made by other devices, so a client pulls only what it needs. (observeSettings)
POST /clientSettings/registerDevice/{deviceId} deviceId (path, String): The stable identifier the client chose for this device.
name (query, String, optional): Human readable name of this device.
platform (query, String, optional): Platform of this device, for example the operating system it runs on.		 JSON ClientDevice JWT Register a device or refresh the name and platform it is listed under. Calling this is optional, since reading or writing the device scope registers the device on its own, but it lets a client give its device a readable name before it stores anything. (registerDevice)
POST /clientSettings/restore scope (query, ClientSettingScope): The scope the key belongs to.
key (query, String): The key to restore.
version (query, Long): The version of the historic value to write back.
device (query, String?, optional): The device to write in the device scope. Required for the device scope and in the synced scope only recorded as the writer.
force (query, Boolean, optional): Whether to apply the value even if the server moved past the version the entry currently has.		 JSON ClientSettingsWriteResult JWT Write a previous value of a key back as a new version. The value is taken from the history of the key and stored through the normal write path, so the scope advances by one and the value that was replaced moves into the history itself. The call fails if the requested version is not kept in the history any more. (restore)
GET /clientSettings/settings scope (query, ClientSettingScope): The scope to read.
device (query, String?, optional): The device to read in the device scope. Required for the device scope and ignored in the synced scope.
includeDeleted (query, Boolean, optional): Whether the tombstones of deleted keys are returned as well.		 JSON List<ClientSetting> JWT Read the entries of a scope. Tombstones of deleted keys are left out unless they are asked for explicitly. Reading the device scope registers the device or refreshes its last seen time. (getSettings)
PUT /clientSettings/settings entries (body, List<ClientSettingWrite>): The entries to write, each with the version the client based its change on.
scope (query, ClientSettingScope): The scope to write to.
device (query, String?, optional): The writing device. Required for the device scope, and in the synced scope only recorded as the writer of the entries.
force (query, Boolean, optional): Whether to apply the entries even if the server moved past the base versions supplied.		 JSON ClientSettingsWriteResult JWT Write a batch of entries into a scope. The batch is all-or-nothing: an entry is accepted only if its base version matches the version the stored entry was last written at, or is 0 for a key that does not exist or is only a tombstone, and as soon as one key conflicts nothing is written at all. Forcing the write skips that check. An entry with a null value deletes its key and leaves a tombstone behind so other devices learn about the deletion. Writing the device scope registers the device or refreshes its last seen time, while the device of a synced write is optional and only recorded as the writer. (setSettings)
GET /clientSettings/snapshot/{deviceId} deviceId (path, String): The stable identifier the client chose for this device. JSON ClientSettingsSnapshot JWT Read the complete settings of a device in one call: the live entries of the synced scope and of the device scope with the current version of each. Reading a snapshot registers the device or refreshes its last seen time, so this is what a client calls right after it starts. (getSnapshot)

/collection — ICollectionService

Management of user-owned downloadable collections.

RPC reference: ICollectionService

Method Path Parameters Response Auth Description
GET /collection/albumIds/{collectionId} collectionId (path, PlatformUUID): The collection unique identifier. SSE PlatformUUID JWT Stream the IDs of albums explicitly added to a collection. (albumIds)
GET /collection/allCollections - JSON List<MediaCollection> JWT Get all collections owned by the current user. (allCollections)
GET /collection/artistIds/{collectionId} collectionId (path, PlatformUUID): The collection unique identifier. SSE PlatformUUID JWT Stream the IDs of artists explicitly added to a collection. (artistIds)
GET /collection/byId/{id} id (path, PlatformUUID): The collection unique identifier. JSON MediaCollection? JWT Get a collection by ID. (byId)
POST /collection/collection collection (body, InsertableCollection): The initial collection data. JSON PlatformUUID JWT Create a new collection owned by the current user. (createCollection)
DELETE /collection/collection/{id} id (path, PlatformUUID): The collection unique identifier. JSON Boolean JWT Delete a collection. (delete)
PUT /collection/collection/{id} id (path, PlatformUUID): The collection unique identifier.
collection (body, InsertableCollection): The new metadata.		 JSON Boolean JWT Update a collection's metadata (name, description, image). (updateCollection)
PUT /collection/collectionImage/{id} id (path, PlatformUUID): The collection unique identifier.
imageId (query, PlatformUUID?, optional): The image unique identifier.		 JSON Boolean JWT Set the cover image of a collection. (setCollectionImage)
DELETE /collection/item/{id} id (path, PlatformUUID): The collection unique identifier.
itemType (query, CollectionItemType): The kind of referenced entity.
itemId (query, PlatformUUID): The referenced entity unique identifier.		 JSON Boolean JWT Remove an item from a collection. (removeItem)
POST /collection/item/{id} id (path, PlatformUUID): The collection unique identifier.
itemType (query, CollectionItemType): The kind of referenced entity.
itemId (query, PlatformUUID): The referenced entity unique identifier.		 JSON Boolean JWT Add an item (song, album, artist or playlist) to a collection. (addItem)
GET /collection/playlistIds/{collectionId} collectionId (path, PlatformUUID): The collection unique identifier. SSE PlatformUUID JWT Stream the IDs of playlists explicitly added to a collection. (playlistIds)
GET /collection/search/{collectionId} collectionId (path, PlatformUUID): The collection unique identifier.
query (query, String): The search query.
explicit (query, Boolean, optional): Whether to include explicit-content songs.
page (query, Int, optional): The page index (starting from 0).
pageSize (query, Int, optional): Items per page, applied per result type.		 JSON CollectionSearchResults JWT Ranked search within a single collection across songs, artists, albums and playlists. (rankedSearch)
GET /collection/songIds/{collectionId} collectionId (path, PlatformUUID): The collection unique identifier. SSE PlatformUUID JWT Stream the IDs of songs explicitly added to a collection. (songIds)

/coverGeneration — ICoverGenerationService

Generates cover images for user playlists and collections from their content, asset packs and palette.

RPC reference: ICoverGenerationService

Method Path Parameters Response Auth Description
POST /coverGeneration/applyCover target (body, CoverTarget): The playlist or collection.
params (body, CoverGenerationParams, optional): Generation parameters.		 JSON PlatformUUID JWT Render, persist and set the cover, marking it as generated. Returns the new image id. Only the owner or an admin may call this. (applyCover)
GET /coverGeneration/coverInfo target (query, JSON, CoverTarget): The playlist or collection. JSON CoverInfo JWT The current cover state of a playlist or collection. (coverInfo)
POST /coverGeneration/generateMissing params (body, CoverGenerationParams, optional): Generation parameters applied to every item. JSON PlatformUUID JWT Queue generation for every playlist and collection of the current user without a cover. Returns the job id. (generateMissing)
GET /coverGeneration/options - JSON CoverGenerationOptions JWT Styles and asset packs available to the current user. (options)
POST /coverGeneration/previewCoverImage target (body, CoverTarget): The playlist or collection.
params (body, CoverGenerationParams, optional): Generation parameters.		 BYTES JWT Render a 1024x1024 JPEG preview without persisting it. Only the owner or an admin may call this. (previewCoverImage)
POST /coverGeneration/resetCover target (body, CoverTarget): The playlist or collection. JSON Boolean JWT Clear a user-set cover so automatic generation may replace it. Returns false when there was nothing to reset. (resetCover)

/customAudio — ICustomAudioService

Handles manual audio uploads.

RPC reference: ICustomAudioService

Method Path Parameters Response Auth Description
POST /customAudio/uploadCustomAudio fileData (body, ByteArray): The raw bytes of the audio file.
fileName (query, String): The original name of the file.
metadata (body, CustomMetadata?, optional): Optional metadata associated with the audio.		 JSON PlatformUUID? JWT + EDIT Upload a custom audio file and its metadata. (uploadCustomAudio)

/dbManagement — IDbManagementService

Direct database management and data migration.

RPC reference: IDbManagementService

Method Path Parameters Response Auth Description
GET /dbManagement/exportData - BYTES JWT + Admin Export the entire system database as a binary blob. (exportData)
POST /dbManagement/importData data (body, ByteArray): The raw database blob. - JWT + Admin Import a previously exported database blob to overwrite the current state. (importData)

/discovery — IDiscoveryService

Service for content discovery and song recommendations.

RPC reference: IDiscoveryService

Method Path Parameters Response Auth Description
POST /discovery/albumMosaic image (body, ByteArray): The source image data.
width (query, Int): Target grid width.
height (query, Int): Target grid height.
page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
range (query, Int, optional): Search range for colors (0-255).		 JSON PaginatedResponse<Album> JWT Create a mosaic of albums matching the colors of an image. (createAlbumMosaic)
GET /discovery/similarSongs seedSongIds (query, repeated, List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (query, Int, optional): The maximum number of results to return.		 JSON List<UserSong> JWT Get songs similar to the provided seed tracks. (getSimilarSongs)
GET /discovery/similarSongsByBpm seedSongIds (query, repeated, List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (query, Int, optional): The maximum number of results to return.		 JSON List<UserSong> JWT Get songs with similar BPM to the provided seed tracks. (getSimilarSongsByBpm)
GET /discovery/similarSongsByEnergy seedSongIds (query, repeated, List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (query, Int, optional): The maximum number of results to return.		 JSON List<UserSong> JWT Get songs with similar energy to the provided seed tracks. (getSimilarSongsByEnergy)
GET /discovery/similarSongsByMood seedSongIds (query, repeated, List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (query, Int, optional): The maximum number of results to return.		 JSON List<UserSong> JWT Get songs with similar mood (valence) to the provided seed tracks. (getSimilarSongsByMood)
GET /discovery/similarSongsByPlaylist/{playlistId} playlistId (path, PlatformUUID): The user playlist unique identifier to use as a seed.
limit (query, Int, optional): The maximum number of results to return.		 JSON List<UserSong> JWT Get songs similar to the songs in the provided user playlist. (getSimilarSongsByPlaylist)
POST /discovery/songMosaic image (body, ByteArray): The source image data.
width (query, Int): Target grid width.
height (query, Int): Target grid height.
page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
range (query, Int, optional): Search range for colors (0-255).		 JSON PaginatedResponse<UserSong> JWT Create a mosaic of songs matching the colors of an image. (createSongMosaic)
GET /discovery/songsBySameComposers seedSongIds (query, repeated, List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (query, Int, optional): The maximum number of results to return.		 JSON List<UserSong> JWT Get songs by the same composers as the provided seed tracks. (getSongsBySameComposers)
GET /discovery/songsBySameLyricists seedSongIds (query, repeated, List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (query, Int, optional): The maximum number of results to return.		 JSON List<UserSong> JWT Get songs by the same lyricists as the provided seed tracks. (getSongsBySameLyricists)
GET /discovery/songsBySameProducers seedSongIds (query, repeated, List<PlatformUUID>): List of song unique identifiers to use as a seed.
limit (query, Int, optional): The maximum number of results to return.		 JSON List<UserSong> JWT Get songs by the same producers as the provided seed tracks. (getSongsBySameProducers)

/entityChange — IEntityChangeService

Answers which library entities changed since a time the client names, so a client that keeps library data reads only those again instead of everything. It is a pull the client starts and not a subscription. Every returned stream delivers the changes recorded so far and then completes, nothing is emitted afterwards. The live notifications are IChangeService.observeChanges. A result contains library changes plus the caller's own LIKE and TIMECODES changes, ordered by time. A filtered pull returns the changes of every object a client gets when it loads that artist, album, playlist or collection, including objects nested in others, such as the artists and the album of a song, the artists of an album and the member artists of an artist that is a group. A change is recorded once for the entity it happened to, so an object nested in several others is reported once as itself, and a client updates the copies it holds by id. A client calls IEntityChangeService.getWindow first, pulls with the time it kept from its last pull and keeps the new one for the next.

RPC reference: IEntityChangeService

Method Path Parameters Response Auth Description
GET /entityChange/allChanges since (query, Long): The time to read from (epoch milliseconds). Entries changed at or after it are returned. SSE EntityChange JWT Stream every recorded change since a time, ordered by time. The stream completes after the last entry. (allChanges)
GET /entityChange/byAlbum/{albumId} albumId (path, PlatformUUID): The album unique identifier.
since (query, Long): The time to read from (epoch milliseconds). Entries changed at or after it are returned.		 SSE EntityChange JWT Stream the recorded changes of everything a client gets when it loads an album since a time, ordered by time. These are the changes of the album itself, of its artists, of its songs, deleted ones included, of every artist credited on those songs, and of the member artists of credited groups. The caller's LIKE changes of the album, these songs and these artists and its TIMECODES changes of these songs are part of it. The stream completes after the last entry. (byAlbum)
GET /entityChange/byArtist/{artistId} artistId (path, PlatformUUID): The artist unique identifier.
since (query, Long): The time to read from (epoch milliseconds). Entries changed at or after it are returned.		 SSE EntityChange JWT Stream the recorded changes of everything a client gets when it loads an artist since a time, ordered by time. These are the changes of the artist itself, of its member artists when it is a group, of its albums and songs, deleted ones included, of the albums of those songs, of every artist credited on those albums and songs, and of the member artists of credited groups. The caller's LIKE changes of these songs, albums and artists and its TIMECODES changes of these songs are part of it. The stream completes after the last entry. (byArtist)
GET /entityChange/byCollection/{collectionId} collectionId (path, PlatformUUID): The collection unique identifier.
since (query, Long): The time to read from (epoch milliseconds). Entries changed at or after it are returned.		 SSE EntityChange JWT Stream the recorded changes of everything a client gets when it loads a collection since a time, ordered by time. These are the changes of the collection itself and of its direct members, which are songs, albums, artists and user playlists. The members are expanded to what they contain. A member album brings its songs, a member artist brings its albums, its songs and the songs of those albums, and a member playlist brings the songs it contains now. For every song reached that way the changes of its album and of its credited artists are returned as well, for every album those of its artists, and for every such artist that is a group those of its member artists. The caller's LIKE changes of these songs, albums and artists and its TIMECODES changes of these songs are part of it. The stream completes after the last entry. (byCollection)
GET /entityChange/byPlaylist/{playlistId} playlistId (path, PlatformUUID): The unique identifier of the user playlist or global playlist.
since (query, Long): The time to read from (epoch milliseconds). Entries changed at or after it are returned.		 SSE EntityChange JWT Stream the recorded changes of everything a client gets when it loads a playlist since a time, ordered by time. These are the changes of the playlist itself, its contents changing included, of the songs it contains now, of the albums of those songs, of every artist credited on those songs and albums, and of the member artists of credited groups. The caller's LIKE changes of these songs, albums and artists and its TIMECODES changes of these songs are part of it. It works for user playlists and global playlists alike. The stream completes after the last entry. (byPlaylist)
GET /entityChange/window - JSON EntityChangeWindow JWT Read the time frame around a pull. The client keeps serverTime as the since of its next pull and compares the since it is about to use with availableSince. If that since lies before availableSince the recorded changes no longer reach back far enough and the client reads everything again. (getWindow)

/favSync — IFavSyncService

Tracks the history of favorite synchronization tasks.

RPC reference: IFavSyncService

Method Path Parameters Response Auth Description
POST /favSync/insertFavSync service (query, SyncServiceType): The service type.
syncedAt (body, PlatformDate): The timestamp of synchronization.		 JSON Int JWT Record a new successful synchronization timestamp. (insertFavSync)
GET /favSync/latestFavSync service (query, SyncServiceType): The service type (e.g., TIDAL). JSON FavSync? JWT Get the timestamp of the last successful synchronization for a specific service. (getLatestFavSync)

/handshake — IHandshakeService

Service for server reachability and handshake testing.

RPC reference: IHandshakeService

Method Path Parameters Response Auth Description
GET /handshake/handshake - JSON HandshakeResponse public Perform a handshake test to check server reachability and protocol support. (handshake)

/hue — IHueService

Philips Hue bridges paired by the current user and their light links, driven by now-playing changes.

RPC reference: IHueService

Method Path Parameters Response Auth Description
DELETE /hue/bridge/{bridgeId} bridgeId (path, PlatformUUID): Server-side bridge unique identifier. JSON Boolean JWT Remove one of the current user's bridges together with the user's link to it. (removeBridge)
GET /hue/bridges - JSON List<HueBridgeInfo> JWT Bridges paired by the current user. (listBridges)
GET /hue/discoverBridges - JSON List<HueBridgeCandidate> JWT Discover Hue bridges on the local network via mDNS and the Hue cloud discovery endpoint. Paired is relative to the current user. (discoverBridges)
PUT /hue/link link (body, HueUserLink): Link settings. bridgeId selects the bridge. JSON HueUserLink JWT Create or update the current user's link to a bridge. (setLink)
DELETE /hue/link/{bridgeId} bridgeId (path, PlatformUUID): Server-side bridge unique identifier. JSON Boolean JWT Remove the current user's link to a bridge. (removeLink)
GET /hue/links - JSON List<HueUserLink> JWT The current user's light links. (getLinks)
GET /hue/scenes/{bridgeId} bridgeId (path, PlatformUUID): Server-side bridge unique identifier. JSON List<HueScene> JWT Scenes exposed by a bridge, each scoped to a room or zone that the bridge reports. (listScenes)
POST /hue/startPairing ip (query, String): IP address of the bridge. SSE HuePairingStatus JWT Pair with a bridge. Press the link button on the bridge while this flow polls for up to 30 seconds. The bridge is stored for the current user. Other users pair it separately. (startPairing)
GET /hue/status - JSON HueStatus JWT Last command time, last error and current colors for the current user's links. (status)
GET /hue/targets/{bridgeId} bridgeId (path, PlatformUUID): Server-side bridge unique identifier. JSON List<HueTarget> JWT Lights, rooms and zones exposed by a bridge. (listTargets)
POST /hue/test/{bridgeId} bridgeId (path, PlatformUUID): Server-side bridge unique identifier.
targets (body, List<HueTarget>): Targets to test.		 JSON Boolean JWT Flash the given targets with a test palette. (test)

/image — IImageService

Management of image files for covers and profiles.

RPC reference: IImageService

Method Path Parameters Response Auth Description
POST /image/batch images (body, List<InsertableImage>): Collection of images to store. JSON Map<String, PlatformUUID> JWT Store multiple images on the server in a single operation. (createBatch)
GET /image/byHash hash (query, String): The unique hash of the image. JSON Image? JWT Find image metadata by its content hash. (byHash)
GET /image/byId/{id} id (path, PlatformUUID): The image unique identifier. JSON Image? JWT Get image metadata by its unique ID. (byId)
GET /image/coverHashes hashes (query, repeated, List<String>): Collection of image hashes. JSON Map<String, PlatformUUID> JWT Map a list of image hashes to their existing internal UUIDs. (getCoverHashes)
POST /image/generateMosaicImage image (body, ByteArray): The source image data.
width (query, Int): Grid width (max width * height = 65,536).
height (query, Int): Grid height (max width * height = 65,536).
resultSize (query, Int, optional): The resolution of the resulting square image.		 SSE MosaicGenerationResponse JWT Generate a mosaic image from a source image where each pixel is replaced by a matching cover. (generateMosaicImage)
POST /image/image bytes (body, ByteArray): The raw binary data of the image.
origin (query, String, optional): The source or category of the image.		 JSON PlatformUUID JWT Store a new image on the server. (createImage)
GET /image/imageData/{id} id (path, PlatformUUID): The image unique identifier.
size (query, Int, optional): Requested image size (width/height). 0 for original size.		 BYTES public Retrieve the raw binary data of an image. (getImageData)
POST /image/moveImages oldPath (query, String): Path prefix to match.
newPath (query, String): New base path.		 JSON Int JWT + Admin Batch update image file paths. (moveImages)

/listenBackup — IListenBackupService

Configure and control the backup of server-side listens to a remote listen-backup receiver.

RPC reference: IListenBackupService

Method Path Parameters Response Auth Description
PUT /listenBackup/config config (body, ListenBackupConfig): The new configuration. A null key keeps the stored key. JSON ListenBackupState JWT + Admin Update the backup configuration. (updateConfig)
GET /listenBackup/observeState - SSE ListenBackupState JWT + Admin Stream the backup state, re-emitting whenever the configuration or sync progress changes. (observeState)
POST /listenBackup/resetCursor - JSON ListenBackupState JWT + Admin Reset the sync cursor so the next run re-pushes every local listen. (resetCursor)
GET /listenBackup/state - JSON ListenBackupState JWT + Admin Get the current backup configuration and sync state. (getState)
POST /listenBackup/syncNow - JSON ListenBackupState JWT + Admin Run a backup sync now and return the resulting state. (syncNow)
POST /listenBackup/testConnection config (body, ListenBackupConfig?, optional): Configuration to probe. Null uses the stored configuration. JSON ListenBackupConnectionTest JWT + Admin Probe a receiver. Uses the stored configuration when no config is given. (testConnection)

/listenBrainz — IListenBrainzService

Manage the current user's ListenBrainz connection and listen-history sync.

RPC reference: IListenBrainzService

Method Path Parameters Response Auth Description
DELETE /listenBrainz/link - - JWT Remove the current user's ListenBrainz link. (unlink)
POST /listenBrainz/link username (query, String): The ListenBrainz username.
token (query, String?, optional): Optional ListenBrainz user token, required for private listens.		 JSON ListenBrainzStatus JWT Link the current user to a ListenBrainz account and trigger an initial sync. (link)
GET /listenBrainz/recentListens limit (query, Int): Maximum number of listens to return. Clamped to 1..1000. JSON List<ListenedSong> JWT Return the current user's most recent listened songs (newest first), capped at 1000. (recentListens)
GET /listenBrainz/status - JSON ListenBrainzStatus? JWT Get the current user's ListenBrainz connection status, or null if not linked. (getStatus)
POST /listenBrainz/syncNow - JSON ListenBrainzStatus JWT Trigger an incremental sync of the current user's ListenBrainz listens now. (syncNow)

/listeningStats — IListeningStatsService

Listening statistics over the current user's unified listen history (local scrobbles and ListenBrainz imports), deduplicated across sources.

RPC reference: IListeningStatsService

Method Path Parameters Response Auth Description
POST /listeningStats/linkUnmatchedTrack request (body, LinkUnmatchedTrackRequest): The unmatched track identity and the target library song. JSON LinkUnmatchedTrackResult JWT Link the current user's unmatched listens of a track to a library song, identified by recording MSID and/or MBID. The link persists, applies to future synced listens, and is submitted to ListenBrainz as a manual mapping when the song has a recording MBID. (linkUnmatchedTrack)
GET /listeningStats/linkedListenGroups/{songId} songId (path, PlatformUUID): The library song. JSON List<LinkedListenGroup> JWT List the groups of the current user's listens that are linked to a library song. Each group can be moved to another song with relinkSong. (getLinkedListenGroups)
POST /listeningStats/relinkSong/{fromSongId} fromSongId (path, PlatformUUID): The library song the listens are linked to now.
toSongId (query, PlatformUUID): The library song to link the listens to.
groups (body, List<LinkedListenGroupKey>?, optional): The groups to move, as returned by getLinkedListenGroups. Null moves every group.		 JSON LinkUnmatchedTrackResult JWT Move the current user's listens from one library song to another, either all of them or only the given groups. The change persists for future listens of the moved groups, including local plays of the same song. It is submitted to ListenBrainz as a manual mapping when the target song has a recording MBID. (relinkSong)
GET /listeningStats/stats range (query, StatsRange): The time range to aggregate.
timezone (query, String): IANA timezone for range boundaries, e.g. Europe/Berlin. Invalid or blank falls back to UTC.
topLimit (query, Int): Maximum entries per top list. Clamped to 1..100.
topOrder (query, TopOrder, optional): Metric used to rank the top and discovery lists.		 JSON ListeningStats JWT Compute listen count, previous-range comparison, top songs/artists/albums, listen clock, streaks, unique counts and new discoveries for a time range. (getStats)
GET /listeningStats/topSongs range (query, StatsRange): The time range to aggregate.
timezone (query, String): IANA timezone for range boundaries, e.g. Europe/Berlin. Invalid or blank falls back to UTC.
limit (query, Int): Maximum number of songs. Clamped to 1..500.
order (query, TopOrder, optional): Metric used to rank the songs.		 JSON List<UserSong> JWT Return the current user's most played songs in a time range as a playable list, ranked by the given metric. Songs that are not in the library are left out. (getTopSongs)

/lyricsCandidate — ILyricsCandidateService

Lyrics of songs from several providers. Every provider answer is kept as a candidate so a client can choose which version to show.

RPC reference: ILyricsCandidateService

Method Path Parameters Response Auth Description
POST /lyricsCandidate/importSyncedLyrics/{songId} songId (path, PlatformUUID): The song unique identifier.
file (body, LyricsImport): The file to import.		 JSON LyricsSearchResult JWT + EDIT Store synced lyrics parsed from a file as the manual candidate of a song. (importSyncedLyrics)
GET /lyricsCandidate/lyrics/{songId} songId (path, PlatformUUID): The song unique identifier.
candidateId (query, PlatformUUID?, optional): The candidate to return instead of the default one.		 JSON LyricsCandidate? JWT Get the lyrics a player shows. This is the default candidate or the given one, with the lyrics filled. Providers are not asked. (getLyrics)
POST /lyricsCandidate/lyrics/{songId} songId (path, PlatformUUID): The song unique identifier.
providers (query, repeated, List<String>?, optional): Identifiers of the providers to ask, or null for all enabled ones.
refresh (query, Boolean, optional): Asks every provider again. Needs the edit capability.		 JSON LyricsSearchResult JWT Get the stored candidates of a song and ask the providers that have not answered yet or are due again. New answers are stored and ranked. (findLyrics)
POST /lyricsCandidate/lyricsByQuery title (query, String): The title of the track.
artist (query, String): The artist of the track.
album (query, String?, optional): The album of the track.
durationMs (query, Long?, optional): The duration of the track in milliseconds.
providers (query, repeated, List<String>?, optional): Identifiers of the providers to ask, or null for all enabled ones.		 JSON LyricsSearchResult JWT Ask the providers for the lyrics of any track. Nothing is stored and the candidates are not tied to a song. (findLyricsByQuery)
GET /lyricsCandidate/lyricsCandidate/{candidateId} candidateId (path, PlatformUUID): The candidate unique identifier. JSON LyricsCandidate? JWT Get one candidate with the lyrics filled. (getLyricsCandidate)
GET /lyricsCandidate/lyricsCandidates/{songId} songId (path, PlatformUUID): The song unique identifier.
includeContent (query, Boolean, optional): Whether to fill the lyrics of every candidate.		 JSON LyricsSearchResult JWT Get the stored candidates of a song. Providers are not asked. (getLyricsCandidates)
GET /lyricsCandidate/lyricsInfo songIds (query, repeated, List<PlatformUUID>): The song unique identifiers. JSON Map<PlatformUUID, SongLyricsInfo> JWT Get the lyrics summary of songs a client already has. (getLyricsInfo)
GET /lyricsCandidate/lyricsProviders - JSON List<LyricsProviderInfo> JWT Get the enabled providers in priority order. (getLyricsProviders)
PUT /lyricsCandidate/preferredLyrics/{songId} songId (path, PlatformUUID): The song unique identifier.
candidateId (query, PlatformUUID?, optional): The candidate to pin, or null to use the best ranked one again.		 JSON LyricsSearchResult JWT + EDIT Pin the default candidate of a song for everyone. (setPreferredLyrics)
GET /lyricsCandidate/streamLyrics/{songId} songId (path, PlatformUUID): The song unique identifier.
providers (query, repeated, List<String>?, optional): Identifiers of the providers to ask, or null for all enabled ones.		 SSE LyricsCandidate JWT Ask the providers for the lyrics of a song and emit each candidate as soon as its provider answers. (streamLyrics)
PUT /lyricsCandidate/syncedLyrics/{songId} songId (path, PlatformUUID): The song unique identifier.
lyrics (body, SyncedLyrics?, optional): The synced lyrics, or null to remove the manual candidate.		 JSON LyricsSearchResult JWT + EDIT Store hand-edited synced lyrics as the manual candidate of a song. A null value removes the manual candidate. (setSyncedLyrics)

/lyricsSearch — ILyricsSearch

Search for track lyrics using external providers.

RPC reference: ILyricsSearch

Method Path Parameters Response Auth Description
GET /lyricsSearch/lyrics artist (query, String): The name of the artist.
title (query, String): The title of the song.
syncedOnly (query, Boolean, optional): Whether to only return time-synced lyrics.		 JSON List<String> JWT Search for lyrics text on external services. (searchLyrics)

/lyrics — ILyricsService

Syncing and management of track lyrics.

RPC reference: ILyricsService

Method Path Parameters Response Auth Description
POST /lyrics/startSyncWorker - JSON Boolean JWT Start the background lyrics synchronization worker. (startSyncWorker)
GET /lyrics/syncedLyrics/{songId} songId (path, PlatformUUID): The song unique identifier. JSON SyncedLyrics? JWT Get time-synced lyrics for a song if they exist. (getSyncedLyrics)
POST /lyrics/transcribeLyrics/{songId} songId (path, PlatformUUID): The song unique identifier.
lyrics (query, String?, optional): Optional raw lyrics text to transcribe.		 JSON SyncedLyrics? JWT Trigger AI-based transcription or manual alignment of lyrics. (transcribeLyrics)

/mirror — IMirrorService

Exposes local data for server-to-server mirroring.

RPC reference: IMirrorService

Method Path Parameters Response Auth Description
GET /mirror/albums - SSE Album JWT + Admin Stream all local albums for mirroring. (getAlbums)
GET /mirror/artistAliases - SSE ArtistAlias JWT + Admin Stream all artist name aliases for mirroring. (getArtistAliases)
GET /mirror/artistSplitAliases - SSE ArtistSplitAlias JWT + Admin Stream all artist split-name mappings for mirroring. (getArtistSplitAliases)
GET /mirror/artists - SSE Artist JWT + Admin Stream all local artists for mirroring. (getArtists)
GET /mirror/imageMetadata - SSE Image JWT + Admin Stream all image metadata for mirroring. (getImageMetadata)
GET /mirror/likedSongs/{userId} userId (path, PlatformUUID): The user unique identifier. SSE Song JWT + Admin Stream all songs liked by a specific user for mirroring. (getLikedSongs)
GET /mirror/playlists - SSE Playlist JWT + Admin Stream all local system playlists for mirroring. (getPlaylists)
GET /mirror/serverPaths - JSON RemoteServerPaths JWT + Admin Expose the local file system paths where media files are stored. (getServerPaths)
GET /mirror/songData/{songId} songId (path, PlatformUUID): The song unique identifier.
quality (query, Int, optional): Target audio quality level.
chunkSize (query, Int, optional): Number of bytes per chunk in the stream.
force (query, Boolean, optional): Whether to force re-transcoding and duration check.		 BYTES JWT + Admin Stream raw audio data for a song. (getSongData)
GET /mirror/songs - SSE Song JWT + Admin Stream all local songs with metadata for mirroring. (getSongs)
GET /mirror/songsByPlaylist/{playlistId} playlistId (path, PlatformUUID): The playlist unique identifier. SSE Song JWT + Admin Stream all songs belonging to a specific system playlist for mirroring. (getSongsByPlaylist)
GET /mirror/songsByUserPlaylist/{playlistId} playlistId (path, PlatformUUID): The playlist unique identifier. SSE Song JWT + Admin Stream all songs belonging to a specific user playlist for mirroring. (getSongsByUserPlaylist)
GET /mirror/userPlaylists - SSE UserPlaylist JWT + Admin Stream all local user playlists for mirroring. (getUserPlaylists)
GET /mirror/users - SSE User JWT + Admin Stream all local user accounts (profiles) for mirroring. (getUsers)

/playback — IPlaybackService

Synchronize music playback status across multiple devices.

RPC reference: IPlaybackService

Method Path Parameters Response Auth Description
GET /playback/observePlaybackState/{sessionId} sessionId (path, PlatformUUID): The session unique identifier. SSE PlaybackState JWT Watch real-time playback state changes for a session. (observePlaybackState)
GET /playback/playbackState/{sessionId} sessionId (path, PlatformUUID): The session unique identifier. JSON PlaybackState? JWT Retrieve the current playback state for a specific session. (getPlaybackState)
PUT /playback/playbackState/{sessionId} sessionId (path, PlatformUUID): The session unique identifier.
state (body, PlaybackState): The new playback state data.		 JSON Boolean JWT Update the playback state for a specific session. (setPlaybackState)

/playlist — IPlaylistService

Management of system playlists.

RPC reference: IPlaylistService

Method Path Parameters Response Auth Description
GET /playlist/allPlaylists page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.		 JSON PaginatedResponse<Playlist> JWT Get all system playlists. (allPlaylists)
GET /playlist/byId/{id} id (path, PlatformUUID): The playlist unique identifier. JSON Playlist? JWT Get system playlist by ID. (byId)
GET /playlist/byIdFull/{id} id (path, PlatformUUID): The playlist unique identifier. JSON Pair<String, List<PlaylistEntry>>? JWT Get system playlist with all track entries. (byIdFull)
GET /playlist/byIds ids (query, repeated, List<PlatformUUID>): Collection of playlist IDs. JSON List<Playlist> JWT Get multiple system playlists by their IDs. (byIds)
GET /playlist/byName name (query, String): The name of the playlist. JSON Playlist? JWT Get system playlist by name. (byName)
DELETE /playlist/playlist/{id} id (path, PlatformUUID): The playlist unique identifier. JSON Boolean JWT + DELETE Delete a system playlist. (delete)
GET /playlist/search page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
query (query, String): The search query.		 JSON PaginatedResponse<Playlist> JWT Search system playlists. (rankedSearch)

/podcast — IPodcastService

Manages podcasts, which are kept completely apart from the music library: an episode is never a song, is never scrobbled and never shows up in music search or statistics. A show is either an RSS feed the server follows or a folder of the local podcast library, and a feed show is stored once and shared by everyone subscribing to it. Subscriptions and listening positions are private to each user and sync across their devices. Episode audio is always played through streamEpisode, no matter whether the server stores the file or relays its origin.

RPC reference: IPodcastService

Method Path Parameters Response Auth Description
GET /podcast/browseShows query (query, String, optional): Search term matched against title, author and description. Blank returns every show.
page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of shows per page, at most 500.		 JSON PaginatedResponse<PodcastShow> JWT Browse every show on the server, both feed shows and shows of the local podcast library, optionally narrowed down by a search term. (browseShows)
GET /podcast/episode/{episodeId} episodeId (path, PlatformUUID): The episode to read. JSON PodcastEpisode? JWT Read a single episode together with the listening position of the user. Returns null if the episode does not exist. (getEpisode)
GET /podcast/episodeWindow/{episodeId} episodeId (path, PlatformUUID): The episode the window is built around.
older (query, Int, optional): How many episodes published before it to read, at most 500. Values below 0 count as none.
newer (query, Int, optional): How many episodes published after it to read, at most 500. Values below 0 count as none.		 JSON List<PodcastEpisode> JWT Read the episodes around one episode of its show: up to older episodes published before it and up to newer published after it, in chronological order with the episode itself included and the listening position of the user on each. Returns an empty list if the episode does not exist. (getEpisodeWindow)
GET /podcast/episodes query (query, String): The search term. Must not be blank.
page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of episodes per page, at most 500.		 JSON PaginatedResponse<PodcastEpisode> JWT Search episodes of every show on the server by their title, their description and the title of their show. (searchEpisodes)
GET /podcast/episodes/{showId} showId (path, PlatformUUID): The show to read the episodes of.
page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of episodes per page, at most 500.
newestFirst (query, Boolean, optional): Whether the newest episode comes first.		 JSON PaginatedResponse<PodcastEpisode> JWT Read a page of episodes of a show, together with the listening position of the user for each of them. (getEpisodes)
GET /podcast/episodesByIds episodeIds (query, repeated, List<PlatformUUID>): The episodes to read, at most 500. JSON List<PodcastEpisode> JWT Read several episodes at once, in the order of the given identifiers, each with the listening position of the user. Unknown identifiers are skipped. At most 500 identifiers. (getEpisodesByIds)
DELETE /podcast/import/{episodeId} episodeId (path, PlatformUUID): The episode whose stored audio is deleted. JSON PodcastEpisode JWT + PODCAST_EDIT Delete the stored audio of an episode of a feed show. The episode itself stays and is played from its origin afterwards. Episodes of the local podcast library cannot be removed this way, as that would delete the file of the user. (removeImport)
POST /podcast/importEpisode/{episodeId} episodeId (path, PlatformUUID): The episode to store on the server. JSON PodcastEpisode JWT + PODCAST_EDIT Queue a single episode to be stored on the server. The transfer itself runs in the background, so the returned episode usually reports that its import is queued. (importEpisode)
GET /podcast/inProgress page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of episodes per page, at most 500.		 JSON PaginatedResponse<PodcastEpisode> JWT Read the episodes the user started but did not finish, the most recently played one first. (getInProgress)
GET /podcast/index query (query, String): The search term. Must not be blank.
limit (query, Int, optional): Maximum number of results, clamped to 1 to 100.
indexes (query, repeated, List<String>, optional): Identifiers of the directories to search, see getIndexes. Empty searches every configured directory.		 JSON List<PodcastIndexResult> JWT Search the podcast directories the server is connected to, for example Podcast Index, for shows by name or topic. Every result carries the address of its feed, so subscribing to it is done with subscribe. Directories that are not configured are skipped, a directory that fails answers with no results, and feeds the server already follows are left out because browseShows lists them. (searchIndex)
GET /podcast/indexes - JSON List<PodcastIndexInfo> JWT Read the podcast directories the server can search and whether each of them is configured. (getIndexes)
GET /podcast/lastPlayed includeCompleted (query, Boolean, optional): Whether an episode the user already completed may be returned. When false only an unfinished episode with a position after the start counts. JSON PodcastEpisode? JWT Read the episode the user played most recently, with the listening position, so a client can offer to continue it. Returns null if the user never played an episode. (getLastPlayed)
GET /podcast/latestEpisodes page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of episodes per page, at most 500.		 JSON PaginatedResponse<PodcastEpisode> JWT Read the newest episodes across the shows the user is subscribed to, newest first. (getLatestEpisodes)
GET /podcast/observeProgress - SSE PodcastEpisodeProgress JWT Watch the listening positions of the user for changes, so other devices follow along while an episode is played somewhere else. (observeProgress)
PUT /podcast/played/{episodeId} episodeId (path, PlatformUUID): The episode to mark.
played (query, Boolean): Whether the episode counts as listened.		 JSON PodcastEpisodeProgress JWT Mark an episode as listened or as unlistened. Marking it as listened moves the position to the end of the episode, marking it as unlistened resets the position to the beginning. (setPlayed)
POST /podcast/refreshShow/{showId} showId (path, PlatformUUID): The show to refresh. JSON PodcastShow JWT Fetch the feed of a show right now and store what changed. The call runs to completion before it returns and is skipped when the feed was already fetched less than 60 seconds ago. (refreshShow)
POST /podcast/reportPlayback report (body, EpisodePlaybackReport): What the client is playing and how far it has got. JSON PodcastEpisodeProgress JWT Store the listening position of the user for an episode. A client reports on play, on pause, after a seek and every 10 to 15 seconds while playing, the same way song playback is reported. The last report wins, and the server marks an episode as completed on its own once the remaining time is under 30 seconds or under 5 percent of its length. (reportPlayback)
POST /podcast/scanLocal - JSON PodcastScanResult JWT + PODCAST_EDIT Scan the local podcast library for new, changed and vanished shows and episodes. The call runs to completion before it returns. (scanLocal)
DELETE /podcast/show/{showId} showId (path, PlatformUUID): The show to remove. JSON Boolean JWT + Admin Remove a feed show from the server for everyone: its episodes, their transcripts, the listening positions of every user and every subscription to it are deleted, and the audio the server stored for it is deleted from disk. Returns false if the show does not exist. Shows of the local podcast library cannot be removed this way, as the server picks them up again on the next scan. (deleteShow)
GET /podcast/show/{showId} showId (path, PlatformUUID): The show to read. JSON PodcastShow? JWT Read a single show. Returns null if the show does not exist. (getShow)
PUT /podcast/showSettings/{showId} showId (path, PlatformUUID): The show to change.
settings (body, PodcastShowSettings): The settings to store for the show.		 JSON PodcastShow JWT + PODCAST_EDIT Change how the server keeps the episodes of a show. Switching a show to import makes the server store new episodes on disk, and the number of episodes to keep must be at least 1 when it is given. With newest retention the server imports the newest episodes and deletes everything beyond that count, while unlistened retention, which needs import delivery, imports the episodes nobody has finished yet and only deletes an episode once every subscriber listened to it to the end, with the keep count capping how many episodes are stored or queued at once. (updateShowSettings)
GET, HEAD /podcast/streamEpisode/{episodeId} episodeId (path, PlatformUUID): The episode to play.
offset (query, Long, optional): Byte offset to start streaming from.
chunkSize (query, Int, optional): Size of each data chunk.		 FILE JWT Stream the audio of an episode. This is the only way a client plays an episode: the server serves the file when the episode is stored on it or belongs to the local podcast library, and relays the audio from its origin otherwise. Returns null if the episode has no audio at all. (streamEpisode)
GET /podcast/streamSize/{episodeId} episodeId (path, PlatformUUID): The episode to read the size of. JSON Long JWT Get the total size of the audio of an episode in bytes, or 0 if the size cannot be determined. (getStreamSize)
POST /podcast/subscribe feedUrl (query, String): The address of the RSS feed to subscribe to. Must be an http or https address of at most 2048 characters. JSON PodcastShow JWT Subscribe to an RSS feed. The feed is fetched and parsed while the call runs when the server does not know it yet, so the call fails if the feed cannot be reached or is not a podcast feed. Subscribing again to a known feed is cheap and does not fetch anything. (subscribe)
POST /podcast/subscribeToShow/{showId} showId (path, PlatformUUID): The show to subscribe to. JSON PodcastShow JWT Subscribe to a show the server already knows, for example one found through browseShows. (subscribeToShow)
GET /podcast/subscriptions - JSON List<PodcastShow> JWT Read the shows the user is subscribed to, ordered by title. (getSubscriptions)
GET /podcast/transcript/{transcriptId} transcriptId (path, PlatformUUID): The transcript to read. JSON PodcastTranscriptContent? JWT Read a single transcript together with its text. A transcript that only exists as a remote address is fetched once on first read and kept afterwards. Returns null if the transcript does not exist or its text cannot be obtained. (getTranscript)
GET /podcast/transcripts/{episodeId} episodeId (path, PlatformUUID): The episode to read the transcripts of. JSON List<PodcastTranscript> JWT Read the transcripts known for an episode without their text. (getTranscripts)
DELETE /podcast/unsubscribe/{showId} showId (path, PlatformUUID): The show to unsubscribe from. JSON Boolean JWT End the subscription of the user to a show. Returns false if the user was not subscribed. The show itself and its episodes stay on the server for a while after the last subscriber leaves. (unsubscribe)

/queue — IQueueService

Manages the server-stored play queue shared between the devices of a user. Every write carries the version the client based its change on. If the server has moved on since then the write is rejected with a conflict carrying the current state, unless the client forces it.

RPC reference: IQueueService

Method Path Parameters Response Auth Description
POST /queue/ackSynced version (query, Long): The queue version this device is now in sync with. - JWT Record that the calling session pulled the queue up to a version, so it can tell later whether the server state is newer than its own. (ackSynced)
POST /queue/beginUpload baseVersion (query, Long): The queue version the upload is based on.
force (query, Boolean, optional): Whether to start the upload even if the server is past the base version.		 JSON QueueUploadStart JWT Start a chunked upload that replaces the whole queue. Entries are staged in memory with uploadPage and become visible only on commitUpload. Starting an upload discards any previous staged upload of the user, and a staged upload expires after a while if it is not committed. (beginUpload)
POST /queue/cancelUpload/{uploadId} uploadId (path, PlatformUUID): The upload identifier returned by beginUpload. - JWT Discard a staged upload without touching the stored queue. (cancelUpload)
POST /queue/commitUpload/{uploadId} uploadId (path, PlatformUUID): The upload identifier returned by beginUpload.
meta (body, QueueMeta): The playback metadata to store with the queue.
requestId (query, PlatformUUID?, optional): The client request this upload answers, if any.		 JSON QueueWriteResult JWT Replace the queue with the staged entries and store the supplied playback metadata. Entries referring to unknown songs are dropped and both orders are renumbered. When the upload answers a queue request of another device, its request identifier is passed so the requester is notified. (commitUpload)
PUT /queue/currentIndex baseVersion (query, Long): The queue version the change is based on.
currentIndex (query, Int): Zero-based index in the active order.
force (query, Boolean, optional): Whether to apply the change even if the server is past the base version.		 JSON QueueWriteResult JWT Set the entry that is currently playing, addressed by its index in the active order. The index is clamped to the size of the queue. (setCurrentIndex)
DELETE /queue/entries baseVersion (query, Long): The queue version the change is based on.
queueIds (query, repeated, List<Long>): The queue identifiers of the entries to remove.
force (query, Boolean, optional): Whether to apply the change even if the server is past the base version.		 JSON QueueWriteResult JWT Remove entries from the queue by their queue identifiers. Unknown identifiers are ignored and the current index is adjusted to stay on the playing entry. (remove)
POST /queue/insert baseVersion (query, Long): The queue version the change is based on.
position (query, Int): Zero-based index in the active order at which the entries are inserted.
items (body, List<QueueItem>): The entries to insert, in the order they should appear.
force (query, Boolean, optional): Whether to apply the change even if the server is past the base version.		 JSON QueueWriteResult JWT Insert entries into the queue at a position of the active order (the shuffled order while shuffle is on, otherwise the original order). With shuffle on the entries are spliced into the shuffled order and appended to the end of the original order. (insert)
PUT /queue/modes baseVersion (query, Long): The queue version the change is based on.
shuffleMode (query, Boolean): Whether the queue is played in shuffled order.
repeatMode (query, RepeatMode): The repetition mode to store.
force (query, Boolean, optional): Whether to apply the change even if the server is past the base version.		 JSON QueueWriteResult JWT Set shuffle and repeat mode. Enabling shuffle makes the server generate a shuffled order that starts with the entry that is currently playing, so the current index becomes 0. Disabling it drops the shuffled order and puts the current index back on the original position of that entry. A player that shuffled on its own uploads its order instead. (setModes)
POST /queue/move/{queueId} baseVersion (query, Long): The queue version the change is based on.
queueId (path, Long): The queue identifier of the entry to move.
toPosition (query, Int): Zero-based target index in the active order.
force (query, Boolean, optional): Whether to apply the change even if the server is past the base version.		 JSON QueueWriteResult JWT Move a single entry to another position of the active order (the shuffled order while shuffle is on, otherwise the original order). (move)
GET /queue/observeQueue - SSE QueueInfo JWT Watch the queue of the user for changes. A new metadata snapshot is emitted after every successful write, including writes made by other devices. (observeQueue)
GET /queue/queue page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
includeSongs (query, Boolean, optional): Resolve each entry's song. Leave false for large queues and fetch songs separately.		 JSON PaginatedResponse<QueueItem> JWT Read a page of queue entries, ordered by their position in the original order. Each entry also carries its shuffled position, and its song metadata only when the entries are requested with the songs resolved. (getQueue)
GET /queue/queueInfo - JSON QueueInfo JWT Get the metadata of the queue without its entries. A user without a stored queue is reported at version 0 with no entries. (getQueueInfo)
POST /queue/requestUploadFrom/{sessionId} sessionId (path, PlatformUUID): The session unique identifier of the device to ask. JSON ClientRequestStatus JWT Ask another device of the same user to upload its current queue and wait for the outcome. The request is delivered over the client request channel. Sessions that are not listening are reported as unreachable and sessions that stay silent as timed out. (requestUploadFrom)
GET /queue/syncDevices - JSON List<QueueSyncDevice> JWT List the devices of the user that take part in queue synchronization, including which entry is the calling session. (getSyncDevices)
PUT /queue/syncEnabled enabled (query, Boolean): Whether this device takes part in queue synchronization.
deviceName (query, String): Human readable name of this device.		 - JWT Opt the calling session in or out of queue synchronization and record the name it is listed under on other devices. (setSyncEnabled)
POST /queue/uploadPage/{uploadId} uploadId (path, PlatformUUID): The upload identifier returned by beginUpload.
items (body, List<QueueItem>): The entries of this page, in upload order.		 JSON Int JWT Stage another page of entries for a started upload. Returns the total number of entries staged so far. (uploadPage)

/radioChannel — IRadioChannelService

Admin-curated radio channels: browse and play for everyone, create and edit for admins.

RPC reference: IRadioChannelService

Method Path Parameters Response Auth Description
POST /radioChannel/channel channel (body, InsertableRadioChannel): The initial channel metadata. JSON PlatformUUID JWT + Admin Create a new radio channel. (createChannel)
DELETE /radioChannel/channel/{id} id (path, PlatformUUID): The channel unique identifier. JSON Boolean JWT + Admin Delete a radio channel. (deleteChannel)
GET /radioChannel/channel/{id} id (path, PlatformUUID): The channel unique identifier. JSON RadioChannel? JWT Get a radio channel by ID. Returns null for a draft channel when the caller is not an admin. (getChannel)
PUT /radioChannel/channel/{id} id (path, PlatformUUID): The channel unique identifier.
channel (body, InsertableRadioChannel): The new metadata.		 JSON Boolean JWT + Admin Update a channel's metadata (name, description, enabled, position, discovery). (updateChannel)
PUT /radioChannel/channelImage/{id} id (path, PlatformUUID): The channel unique identifier.
bytes (body, ByteArray): The raw bytes of the image.		 - JWT + Admin Set the channel's cover image from raw bytes. (setChannelImage)
GET /radioChannel/channels - JSON List<RadioChannel> JWT List radio channels. Non-admin users only see published channels. (listChannels)
GET /radioChannel/search/{channelId} channelId (path, PlatformUUID): The channel unique identifier.
query (query, String, optional): The search query. Empty to list all configured content.
explicit (query, Boolean, optional): Whether to include explicit-content songs.
page (query, Int, optional): The page index (starting from 0).
pageSize (query, Int, optional): Items per page, applied per result type.		 JSON RadioChannelSearchResults JWT Ranked search across the songs, artists and albums configured on a channel. An empty query lists all configured content. (rankedSearch)
POST /radioChannel/startChannel/{id} id (path, PlatformUUID): The channel unique identifier. JSON PlatformUUID JWT Start playing a channel. Returns a radio session id to feed into IRadioService.observeRadio. (startChannel)
DELETE /radioChannel/{type}/channelItem/{id} id (path, PlatformUUID): The channel unique identifier.
type (path, RadioChannelItemType): The kind of referenced entity.
itemId (query, PlatformUUID): The referenced entity unique identifier.		 JSON Boolean JWT + Admin Remove a song, artist or album from a channel's configured content. (removeChannelItem)
POST /radioChannel/{type}/channelItem/{id} id (path, PlatformUUID): The channel unique identifier.
type (path, RadioChannelItemType): The kind of referenced entity.
itemId (query, PlatformUUID): The referenced entity unique identifier.		 JSON Boolean JWT + Admin Add a song, artist or album to a channel's configured content. (addChannelItem)

/radio — IRadioService

Infinite radio stations seeded from listen history, a seed selection, or pure randomness.

RPC reference: IRadioService

Method Path Parameters Response Auth Description
GET /radio/observeRadio/{sessionId} sessionId (path, PlatformUUID): The radio session identifier, as returned by createRadioSession. SSE PlatformUUID JWT Infinite stream of song identifiers for a radio session. Re-collecting the same session continues without repeating songs. (observeRadio)
POST /radio/radioSession type (query, RadioType, optional): The strategy used to seed the station. Ignored when a seed is provided.
seed (body, RadioSeed?, optional): Optional seed material. When set, the station plays songs similar to the seed.		 JSON PlatformUUID JWT Create a radio session and return its identifier. The same identifier can be reused to resume the station where it left off. (createRadioSession)

/recommendation — IRecommendationService

Personalized music recommendations from the learned embedding space.

RPC reference: IRecommendationService

Method Path Parameters Response Auth Description
GET /recommendation/mix window (query, RecommendationWindow, optional): Recency window used to seed the mix.
limit (query, Int, optional): The maximum number of results to return.		 JSON List<UserSong> JWT A personalized mix seeded from the user's recent listens over a time window. (getMix)
GET /recommendation/moodPlaylist mood (query, String): The mood label, as returned by getMoods.
limit (query, Int, optional): The maximum number of results to return.		 JSON List<UserSong> JWT Songs belonging to a given mood cluster. (getMoodPlaylist)
GET /recommendation/moods - JSON List<MoodSummary> JWT Available mood labels with their song counts. (getMoods)
GET /recommendation/similarSongs seedSongIds (query, repeated, List<PlatformUUID>): Seed song unique identifiers.
limit (query, Int, optional): The maximum number of results to return.		 JSON List<UserSong> JWT Songs most similar to the given seed songs in the learned embedding space. (getSimilarSongs)

/release — IReleaseService

Track and receive notifications for new music releases.

RPC reference: IReleaseService

Method Path Parameters Response Auth Description
GET /release/artistRecentReleases/{artistId} artistId (path, PlatformUUID): The artist unique identifier.
page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
includeHidden (query, Boolean, optional): Include entries that have been hidden from the feed. They carry hidden = true.		 JSON PaginatedResponse<RecentRelease> JWT Retrieve recent music releases for a specific artist. Editions of one release are folded into a single entry carrying the others in versions. (getArtistRecentReleases)
POST /release/confirmRelease/{releaseId} releaseId (path, PlatformUUID): The provider release id of the flagged entry. JSON RecentRelease JWT + EDIT Confirm that a provider entry flagged as possibly belonging to another artist is correct: clears the flag and records the entry's copyright holder, record label and ISRC registrants as known sources of the artist so future catalog runs do not flag matching entries again. Returns the updated entry. (confirmRelease)
POST /release/followArtist/{musicBrainzId} musicBrainzId (path, PlatformUUID): The MusicBrainz Artist UUID. JSON Boolean JWT Follow an artist by their MusicBrainz ID to track their releases. (followArtist)
GET /release/followedArtists - JSON List<FollowedArtist> JWT Get a list of all artists the current user is following. (getFollowedArtists)
GET /release/recentReleases page (query, Int, optional): Page index, applied to every release type separately.
pageSize (query, Int, optional): Number of entries per page for each release type.		 JSON PaginatedResponse<RecentRelease> JWT Retrieve a feed of recent and upcoming music releases from followed artists, merged from MusicBrainz and the Apple Music catalog. Editions of one release are folded into a single entry carrying the others in versions. Paging applies per release type: one page holds up to pageSize entries of every type, a folded group counting once, in one list sorted by date. (getRecentReleases)
GET /release/recentReleasesByMusicBrainzId/{musicBrainzId} musicBrainzId (path, PlatformUUID): The MusicBrainz Artist UUID.
page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.		 JSON PaginatedResponse<RecentRelease> JWT Retrieve recent music releases for an artist by their MusicBrainz ID. (getRecentReleasesByMusicBrainzId)
POST /release/refreshRecentRelease/{releaseId} releaseId (path, PlatformUUID): The MusicBrainz release-group UUID of the recent release to refresh, or the provider release id for non-MusicBrainz sources. - JWT + EDIT Kick off a background refresh of the cached metadata, provider links and cover image for a single recent release, returning immediately. (refreshRecentRelease)
PUT /release/releaseHidden/{releaseId} releaseId (path, PlatformUUID): The MusicBrainz release-group UUID of the recent release, or the provider release id for non-MusicBrainz sources.
hidden (query, Boolean): true to hide the entry, false to show it again.
includeRelated (query, Boolean, optional): Also apply the change to the artist's Apple Music entries sharing the copyright holder or record label and record or clear the block. Ignored for MusicBrainz entries.		 JSON Int JWT + EDIT Hide an entry of the release feed for every user, or show it again. With includeRelated the other Apple Music entries of the same artist sharing the entry's copyright holder (or record label when no holder is known) are hidden or shown as well, and the holder or label is recorded as blocked (or unblocked) for the artist so future catalog runs hide matching entries automatically. Returns the number of entries whose visibility changed. The change applies to the whole display group, i.e. every edition the feed folds under one entry. (setReleaseHidden)
GET /release/releaseImage/{releaseId} releaseId (path, PlatformUUID): The MusicBrainz release-group UUID of the recent release, or the provider release id for non-MusicBrainz sources.
size (query, Int, optional): Requested image size (width/height). 0 for original size.		 BYTES public Retrieve the cover image for a recent release, served from local storage when persisted or proxied from the Cover Art Archive on demand. (getReleaseImage)
DELETE /release/unfollowArtist/{artistId} artistId (path, PlatformUUID): The artist unique identifier. JSON Boolean JWT Unfollow an artist and stop tracking their releases. (unfollowArtist)
DELETE /release/unfollowArtistByMusicBrainzId/{musicBrainzId} musicBrainzId (path, PlatformUUID): The MusicBrainz Artist UUID. JSON Boolean JWT Unfollow an artist by their MusicBrainz ID and stop tracking their releases. (unfollowArtistByMusicBrainzId)

/remoteControl — IRemoteControlService

Controls playback on another device of the same user and watches what it is doing. Only devices that are connected to the request channel offering the remote control capability can be reported on or addressed, and a device is always addressed by its session. Nothing here is stored: a status lives as long as the device stays connected.

RPC reference: IRemoteControlService

Method Path Parameters Response Auth Description
GET /remoteControl/observeStatus/{sessionId} sessionId (path, PlatformUUID): The session unique identifier of the device to watch. SSE RemotePlaybackStatus JWT Watch what another device of the user is playing. The last reported status is replayed immediately, followed by every later report. (observeStatus)
POST /remoteControl/reportStatus status (body, RemotePlaybackStatus): What this device is playing right now. The report timestamp is filled in by the server. - JWT Publish what the calling session is playing, which every device watching it receives. A client reports after every change and every few seconds while it is playing, so watchers can follow the position. The calling session must be connected offering remote control. (reportStatus)
POST /remoteControl/sendCommand/{sessionId} sessionId (path, PlatformUUID): The session unique identifier of the device to control.
command (body, PlaybackCommand): The transport command to apply on that device.		 JSON ClientRequestStatus JWT Send a transport command to another device of the user and wait for it to answer. The device must be connected offering remote control, and a volume command additionally requires the remote volume capability and a volume between 0 and 1. A device that stays silent is reported as timed out after ten seconds. (sendCommand)
GET /remoteControl/status/{sessionId} sessionId (path, PlatformUUID): The session unique identifier of the device to read. JSON RemotePlaybackStatus? JWT Read the last status another device of the user reported, or null when it has not reported anything since it connected. (getStatus)

/remoteMirror — IRemoteMirrorService

Instance-to-instance data synchronization.

RPC reference: IRemoteMirrorService

Method Path Parameters Response Auth Description
GET /remoteMirror/activeMirrorProgress - SSE MirrorProgress JWT + Admin Stream real-time progress updates for the active mirroring task. (getActiveMirrorProgress)
POST /remoteMirror/proxyInstances config (body, RemoteServerConfig): Remote connection configuration. JSON List<ProxyInstanceInfo> JWT + Admin List available proxy instances on a remote Synara instance. (getProxyInstances)
POST /remoteMirror/remoteImageData/{imageId} config (body, RemoteServerConfig): Remote connection configuration.
imageId (path, PlatformUUID): The unique identifier of the image.
size (query, Int): Requested image size (width/height).		 BYTES JWT + Admin Fetch raw image binary data from a remote Synara instance. (getRemoteImageData)
POST /remoteMirror/remotePlaylists config (body, RemoteServerConfig): Remote connection configuration. JSON List<Playlist> JWT + Admin List all system playlists on a remote Synara instance. (getRemotePlaylists)
POST /remoteMirror/remoteStats config (body, RemoteServerConfig): Connection configuration for the remote server. JSON ServerStats JWT + Admin Get statistics from a remote Synara instance. (getRemoteStats)
POST /remoteMirror/remoteUserPlaylists config (body, RemoteServerConfig): Remote connection configuration. JSON List<UserPlaylist> JWT + Admin List all user playlists on a remote Synara instance. (getRemoteUserPlaylists)
POST /remoteMirror/remoteUsers config (body, RemoteServerConfig): Remote connection configuration. JSON List<User> JWT + Admin List all user accounts on a remote Synara instance. (getRemoteUsers)
POST /remoteMirror/resetMirror - - JWT + Admin Reset the internal mirroring state. (resetMirror)
POST /remoteMirror/startMirror config (body, RemoteServerConfig): Mirroring configuration and credentials. - JWT + Admin Start mirroring content from another Synara instance. (startMirror)
POST /remoteMirror/stopMirror - - JWT + Admin Stop the active mirroring process. (stopMirror)

/rpcMetrics — IRpcMetricsService

Admin-only access to RPC call usage metrics (how often each call is invoked, per user and over time).

RPC reference: IRpcMetricsService

Method Path Parameters Response Auth Description
POST /rpcMetrics/lifetimeTotals limit (query, Int, optional): Maximum number of rows to return.
username (query, String?, optional): Optional username filter. Null returns totals across all users.		 JSON List<RpcCallTotal> JWT + Admin Lifetime invocation totals per call, ordered by count descending. These counters are never pruned. (lifetimeTotals)
POST /rpcMetrics/recentEvents limit (query, Int, optional): Maximum number of events to return. JSON List<RpcCallEvent> JWT + Admin The most recent recorded invocations from the capped event log, newest first. (recentEvents)
POST /rpcMetrics/timeSeries service (query, String): The RPC service (interface) name, e.g. "ISongService".
method (query, String): The RPC method (call) name.
sinceMillis (query, Long): Only include buckets at or after this epoch-millis timestamp.		 JSON List<RpcCallStat> JWT + Admin Hourly time-series of invocation counts for a specific call, oldest first. (timeSeries)

/scheduledTaskConfiguration — IScheduledTaskConfigurationService

Management of background task configurations.

RPC reference: IScheduledTaskConfigurationService

Method Path Parameters Response Auth Description
PUT /scheduledTaskConfiguration/configuration configuration (body, TaskConfiguration) - JWT + Admin Update a task configuration. (updateConfiguration)
GET /scheduledTaskConfiguration/configurations - JSON List<TaskConfiguration> JWT + Admin Retrieve all background task configurations. (getConfigurations)
GET /scheduledTaskConfiguration/observeConfigurations - SSE List<TaskConfiguration> JWT + Admin Stream real-time updates for all background task configurations. (observeConfigurations)
POST /scheduledTaskConfiguration/triggerTask key (query, String) JSON Boolean JWT + Admin Manually trigger a background task by its unique key. (triggerTask)

/scheduledTaskLog — IScheduledTaskLogService

Monitoring and tracking of background scheduled tasks.

RPC reference: IScheduledTaskLogService

Method Path Parameters Response Auth Description
GET /scheduledTaskLog/groupedLogs - JSON Map<String, List<ScheduledTaskLog>> JWT + Admin Retrieve a snapshot of the most recent background task logs grouped by task name. (getGroupedLogs)
GET /scheduledTaskLog/observeGroupedLogs - SSE Map<String, List<ScheduledTaskLog>> JWT + Admin Stream real-time updates for all background task progress and completion. (observeGroupedLogs)

/scrobble — IScrobbleService

Submit playback scrobbles and observe the current user's recently listened songs, artists and albums.

RPC reference: IScrobbleService

Method Path Parameters Response Auth Description
POST /scrobble/clearNowPlaying - - JWT Clear the current user's now-playing state, e.g. when playback stops. (clearNowPlaying)
POST /scrobble/listened request (body, ScrobbleRequest): The completed listen. - JWT Record that the current user finished listening to a library song. (listened)
POST /scrobble/nowPlaying/{songId} songId (path, PlatformUUID): The library song now playing. - JWT Report the library song the current user is now playing. Auto-clears after the song's duration unless reported again. (nowPlaying)
GET /scrobble/recentAlbums limit (query, Int): Maximum number of albums to return. Clamped to 1..1000. JSON List<ListenedAlbum> JWT Get the current user's recently listened albums, most recently played first. (recentAlbums)
GET /scrobble/recentArtists limit (query, Int): Maximum number of artists to return. Clamped to 1..1000. JSON List<ListenedArtist> JWT Get the current user's recently listened artists, most recently played first. (recentArtists)
GET /scrobble/recentListens limit (query, Int): Maximum number of recent songs to return. Clamped to 1..1000. JSON RecentListens JWT Get the current user's recently listened songs and current now-playing once. (recentListens)
POST /scrobble/reportPlayback report (body, PlaybackReport): The current playback state. JSON Long JWT Report playback progress for the current user: call on play, pause, resume, seek and every 10-15 seconds while playing. Returns the server's epoch milliseconds at receipt so clients can align their clocks. (reportPlayback)

/serverStats — IServerStatsService

Basic server health and performance monitoring.

RPC reference: IServerStatsService

Method Path Parameters Response Auth Description
GET /serverStats/health - JSON Boolean public Simple connectivity check to verify the server is responding. (health)
GET /serverStats/proxyInfo - JSON ProxyInfo? public Retrieve information about the reverse proxy status and configuration. (getProxyInfo)
GET /serverStats/stats - JSON ServerStats public Retrieve detailed system performance metrics and library statistics. (getStats)

/session — ISessionService

Manages active user sessions and connected devices.

RPC reference: ISessionService

Method Path Parameters Response Auth Description
DELETE /session/deactivateSession/{sessionId} sessionId (path, PlatformUUID): The session unique identifier. - JWT Terminate a specific user session. (deactivateSession)
GET /session/sessions - JSON List<Session> JWT List all sessions for the current user. (getSessions)

/song — ISongService

The primary interface for song discovery, streaming, and metadata.

RPC reference: ISongService

Method Path Parameters Response Auth Description
GET /song/allSongIds explicit (query, Boolean): Whether to include explicit content.
tags (query, repeated, List<SongTag>, optional): Only include songs that match any of these tags.
excludeTags (query, repeated, List<SongTag>, optional): Exclude songs that match any of these tags. All filters combine with AND.
titleTags (query, repeated, List<TitleTagKind>, optional): Only include songs whose title carries any of these title tag kinds.
excludeTitleTags (query, repeated, List<TitleTagKind>, optional): Exclude songs whose title carries any of these title tag kinds. Songs without title tags are kept.		 SSE PlatformUUID JWT Stream all song IDs with optional filtering. (allSongIds)
GET /song/allSongs page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
explicit (query, Boolean): Whether to include explicit content.
tags (query, repeated, List<SongTag>, optional): Only include songs that match any of these tags.
excludeTags (query, repeated, List<SongTag>, optional): Exclude songs that match any of these tags. All filters combine with AND.
titleTags (query, repeated, List<TitleTagKind>, optional): Only include songs whose title carries any of these title tag kinds.
excludeTitleTags (query, repeated, List<TitleTagKind>, optional): Exclude songs whose title carries any of these title tag kinds. Songs without title tags are kept.		 JSON PaginatedResponse<UserSong> JWT Get all songs with optional filtering. (allSongs)
PUT /song/artists/{id} id (path, PlatformUUID): The song unique identifier.
artistIds (query, repeated, List<PlatformUUID>): Collection of artist IDs.		 JSON UserSong? JWT + EDIT Update song artists. (setArtists)
GET /song/atmosStreamSize/{id} id (path, PlatformUUID): The song unique identifier. JSON Long JWT Get the size of the song's Dolby Atmos stream, or 0 if the song has no Atmos variant. (getAtmosStreamSize)
GET /song/byAlbum/{albumId} page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
albumId (path, PlatformUUID): The album unique identifier.		 JSON PaginatedResponse<UserSong> JWT List songs in an album. (byAlbum)
GET /song/byArtist/{artistId} page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
artistId (path, PlatformUUID): The artist unique identifier.		 JSON PaginatedResponse<UserSong> JWT List songs by a specific artist. (byArtist)
GET /song/byColor page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
color (query, Int): The target color in ARGB format.
range (query, Int, optional): The allowed range (0-255).
explicit (query, Boolean): Whether to include explicit content.		 JSON PaginatedResponse<UserSong> JWT Search for songs by color. (byColor)
GET /song/byId/{id} id (path, PlatformUUID): The song unique identifier. JSON UserSong? JWT Get song by its unique identifier. (byId)
GET /song/byIds ids (query, repeated, List<PlatformUUID>): Collection of song IDs. JSON List<UserSong> JWT Get multiple songs by their unique identifiers. (byIds)
GET /song/byLyrics page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
query (query, String): The search query.
explicit (query, Boolean): Whether to include explicit content.		 JSON PaginatedResponse<UserSong> JWT Search for songs by their lyrics. (searchByLyrics)
GET /song/byMusicBrainzId/{musicBrainzId} musicBrainzId (path, PlatformUUID): The MusicBrainz Recording UUID. JSON List<UserSong> JWT Find songs by their MusicBrainz Recording ID. (byMusicBrainzId)
GET /song/byOriginalIds ids (query, repeated, Collection<PrefixedId>): Collection of original platform-specific track identifiers. JSON List<UserSong> JWT Find songs by their original platform-specific unique identifiers. (byOriginalIds)
GET /song/byOriginalTracks tracks (query, JSON, Collection<Track>): Collection of track metadata. JSON List<UserSong> JWT Find songs matching external metadata records. (byOriginalTracks)
GET /song/byOriginalUrls urls (query, repeated, Collection<String>): Collection of original platform URLs. JSON Map<String, UserSong?> JWT Find songs by their original platform URLs, returning a mapping. (byOriginalUrls)
GET /song/byPlaylist/{playlistId} page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
playlistId (path, PlatformUUID): The playlist unique identifier.		 JSON PaginatedResponse<UserSong> JWT List songs in a system playlist. (byPlaylist)
GET /song/byTitle page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
title (query, String): The song title to search for.		 JSON PaginatedResponse<UserSong> JWT Search for songs by title. (byTitle)
GET /song/byUserPlaylist/{playlistId} page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
playlistId (path, PlatformUUID): The user playlist unique identifier.		 JSON PaginatedResponse<UserSong> JWT List songs in a user playlist. (byUserPlaylist)
GET /song/downloadSize/{id} id (path, PlatformUUID): The song unique identifier.
quality (query, Int): The requested quality.
force (query, Boolean, optional): Whether to force re-transcoding and duration check.
format (query, AudioFormat, optional): The target audio format.		 JSON Long JWT Get the size of the song audio for a specific quality. (getDownloadSize)
GET /song/downloadSizes ids (query, repeated, List<PlatformUUID>): The song unique identifiers.
quality (query, Int): The requested quality in kbps, or a value <= 0 for the original file.
format (query, AudioFormat, optional): The target audio format.		 JSON List<SongDownloadSize> JWT Get the recorded download sizes of songs for a quality and format, without transcoding. Songs without a recorded size are left out. (getDownloadSizes)
GET, HEAD /song/downloadSong/{id} id (path, PlatformUUID): The song unique identifier.
quality (query, Int): Target audio quality.
offset (query, Long, optional): Byte offset to start from.
chunkSize (query, Int, optional): Size of each data chunk.
force (query, Boolean, optional): Whether to force re-transcoding and duration check.
format (query, AudioFormat, optional): The target audio format.		 FILE JWT Download song audio in specific quality. (downloadSong)
GET /song/exportFavouritesAsCsv - JSON String JWT Export all favorited songs as a CSV string. (exportFavouritesAsCsv)
GET /song/extendedMetadata/{id} id (path, PlatformUUID): The song unique identifier. JSON SongExtendedMetadata? JWT Get extended metadata for a song. (extendedMetadata)
PUT /song/likeLevel/{id} id (path, PlatformUUID): The unique UUID of the song.
level (query, LikeLevel): The new like level. NONE removes the like and the super like.		 JSON UserSong? JWT Set the like level of a song. A super like also counts as a like. Changing between LIKE and SUPER keeps the song's position among the liked songs. (setLikeLevel)
GET /song/likedByArtist/{artistId} page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
artistId (path, PlatformUUID): The artist unique identifier.
explicit (query, Boolean): Whether to include explicit content.		 JSON PaginatedResponse<UserSong> JWT List songs liked by the user for a specific artist. (likedByArtist)
GET /song/likedSongIds explicit (query, Boolean): Whether to include explicit content. SSE PlatformUUID JWT Stream all IDs of songs liked by the current user. (likedSongIds)
GET /song/likedSongs page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
explicit (query, Boolean): Whether to include explicit content.		 JSON PaginatedResponse<UserSong> JWT Get all songs liked by the current user. (likedSongs)
PUT /song/lyrics/{id} id (path, PlatformUUID): The song unique identifier.
lyrics (query, repeated, List<String>): List of lyric lines.		 JSON UserSong? JWT + EDIT Manually set song lyrics. (setLyrics)
POST /song/moveSongs oldPath (query, String): Path prefix to match.
newPath (query, String): New base path.
originalIdPrefix (query, String?, optional): Optional originalId prefix to filter by.		 JSON Int JWT + Admin Batch update song file paths. (moveSongs)
POST /song/musicBrainzId/{id} id (path, PlatformUUID): The song unique identifier. JSON UserSong? JWT + EDIT Trigger automatic MusicBrainz ID matching for a song. (fetchMusicBrainzId)
PUT /song/musicBrainzId/{id} id (path, PlatformUUID): The song unique identifier.
musicBrainzId (query, PlatformUUID?, optional): The MusicBrainz Recording UUID.		 JSON UserSong? JWT + EDIT Link a song to its MusicBrainz Recording record. (setMusicBrainzId)
GET /song/search page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
query (query, String): The search query.
explicit (query, Boolean): Whether to include explicit content.
liked (query, Boolean, optional): Only search within liked songs.		 JSON PaginatedResponse<UserSong> JWT Perform a ranked search for songs. (rankedSearch)
PUT /song/song song (body, Song): The song with its updated editable fields. JSON UserSong? JWT + EDIT Update a song's editable metadata (title, artists and their credited names, MusicBrainz link, album, release date, track and disc number). (updateSong)
GET /song/songIdsByAlbum/{albumId} albumId (path, PlatformUUID): The album unique identifier. SSE PlatformUUID JWT Stream song IDs belonging to an album. (songIdsByAlbum)
GET /song/songIdsByArtist/{artistId} artistId (path, PlatformUUID): The artist unique identifier. SSE PlatformUUID JWT Stream song IDs belonging to an artist. (songIdsByArtist)
GET /song/songIdsByPlaylist/{playlistId} playlistId (path, PlatformUUID): The playlist unique identifier. SSE PlatformUUID JWT Stream song IDs belonging to a system playlist. (songIdsByPlaylist)
GET /song/songIdsByUserPlaylist/{playlistId} playlistId (path, PlatformUUID): The user playlist unique identifier. SSE PlatformUUID JWT Stream song IDs belonging to a user playlist. (songIdsByUserPlaylist)
DELETE /song/songs ids (query, repeated, List<PlatformUUID>): Collection of song IDs to delete. JSON Boolean JWT + DELETE Delete multiple songs from the library. (deleteSongs)
GET /song/streamSize/{id} id (path, PlatformUUID): The song unique identifier. JSON Long JWT Get the total size of the song's audio stream. (getStreamSize)
GET, HEAD /song/streamSong/{id} id (path, PlatformUUID): The song unique identifier.
offset (query, Long, optional): Byte offset to start streaming from.
chunkSize (query, Int, optional): Size of each data chunk.		 FILE JWT Stream song audio data for playback. (streamSong)
GET, HEAD /song/streamSongAtmos/{id} id (path, PlatformUUID): The song unique identifier.
offset (query, Long, optional): Byte offset to start streaming from.
chunkSize (query, Int, optional): Size of each data chunk.		 FILE JWT Stream the Dolby Atmos (E-AC-3 JOC in MP4) variant of a song. Returns null if the song has no Atmos variant. (streamSongAtmos)
GET /song/superLikedSongIds explicit (query, Boolean): Whether to include explicit content. SSE PlatformUUID JWT Stream all IDs of songs super liked by the current user, most recently super liked first. (superLikedSongIds)
GET /song/superLikedSongs page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
explicit (query, Boolean): Whether to include explicit content.		 JSON PaginatedResponse<UserSong> JWT Get all songs super liked by the current user, most recently super liked first. (superLikedSongs)

/storage — IStorageService

Monitoring of physical disk usage for the media library.

RPC reference: IStorageService

Method Path Parameters Response Auth Description
GET /storage/totalStorage - JSON Long JWT Calculate and return the total storage space consumed by the music library in bytes. (getTotalStorage)

/subsonicCredential — ISubsonicCredentialService

Manages the current user's dedicated Subsonic credential used by Subsonic/OpenSubsonic clients.

RPC reference: ISubsonicCredentialService

Method Path Parameters Response Auth Description
POST /subsonicCredential/regenerateSubsonicCredential - JSON SubsonicCredentialInfo JWT Generate a new Subsonic credential for the current user, replacing any existing one. (regenerateSubsonicCredential)
DELETE /subsonicCredential/revokeSubsonicCredential - JSON Boolean JWT Delete the current user's Subsonic credential. Returns true if a credential was deleted. (revokeSubsonicCredential)
GET /subsonicCredential/subsonicCredential - JSON SubsonicCredentialInfo? JWT Get the current user's Subsonic credential, or null if none exists. (getSubsonicCredential)

/timecodeTag — ITimecodeTagService

Stores the tags a user attaches to a song at a position in milliseconds, either as a chapter that names a section, as a marker that points at a single moment or as a free-form note. Tags are private to the user who created them, so they are never visible to anyone else, and a tag disappears together with the song it belongs to. The text of a tag holds at most 1000 characters and a user keeps at most 500 tags on a single song.

RPC reference: ITimecodeTagService

Method Path Parameters Response Auth Description
DELETE /timecodeTag/tag/{tagId} tagId (path, PlatformUUID): The tag to delete. JSON Boolean JWT Delete a single tag of the user. Returns false if the tag does not exist or belongs to another user. (deleteTag)
PUT /timecodeTag/tag/{tagId} tagId (path, PlatformUUID): The tag to change.
tagType (query, TimecodeTagType): How the tag is meant to be read by a client.
text (query, String, optional): The text of the tag. May be blank.
timestampMs (query, Long): Position in the song in milliseconds at which the tag starts.
endMs (query, Long?, optional): Position in the song in milliseconds at which the tag ends, or null for a tag that marks a single point.
action (query, TimecodeTagAction?, optional): What the playing client does when playback reaches the tag, or null to keep the stored action.
fade (query, Boolean?, optional): Whether the client fades in from the tag and fades out towards the tag around the action, or null to keep the stored value.		 JSON TimecodeTag JWT Overwrite a single tag of the user with new values. The call fails if the tag does not exist or belongs to another user. An action or fade flag left out keeps the stored value, and the resulting action must fit the type: PLAY_ONLY and SKIP need a chapter with an end position, SKIP_TO and PLAY_UNTIL need a marker without one, and a note only takes NONE. (updateTag)
GET /timecodeTag/tags tagType (query, TimecodeTagType?, optional): Only return tags of this kind, or null for every kind.
page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of tags per page, at most 500.		 JSON PaginatedResponse<TimecodeTag> JWT Read the tags of the user across all songs, newest first, optionally narrowed down to a single kind of tag. (listTags)
GET /timecodeTag/tags/{songId} songId (path, PlatformUUID): The song to read the tags of. JSON List<TimecodeTag> JWT Read the tags the user attached to a song, ordered by the position they start at. (getTags)
POST /timecodeTag/tags/{songId} songId (path, PlatformUUID): The song to attach the tag to.
tagType (query, TimecodeTagType): How the tag is meant to be read by a client.
text (query, String, optional): The text of the tag. May be blank.
timestampMs (query, Long): Position in the song in milliseconds at which the tag starts.
endMs (query, Long?, optional): Position in the song in milliseconds at which the tag ends, or null for a tag that marks a single point.
action (query, TimecodeTagAction, optional): What the playing client does when playback reaches the tag.
fade (query, Boolean, optional): Whether the client fades in from the tag and fades out towards the tag around the action.		 JSON TimecodeTag JWT Create a single tag on a song. The position must not be negative and an end position, if one is given, must not lie before the position the tag starts at. The action must fit the type: PLAY_ONLY and SKIP need a chapter with an end position, SKIP_TO and PLAY_UNTIL need a marker without one, and a note only takes NONE. (createTag)
PUT /timecodeTag/tags/{songId} songId (path, PlatformUUID): The song whose tags are replaced.
tags (body, List<TimecodeTagInput>): The tags to store for the song. An empty list removes every tag of the song.		 JSON List<TimecodeTag> JWT Replace every tag the user has on a song with the supplied ones. The write is all-or-nothing, so either all tags are stored or none of them are, and an empty list clears the tags of the song. Each tag carries its action and fade flag, which follow the same rules as in createTag. (replaceTags)

/ui — IUiService

Server-driven UI: lists, renders and drives slot, page and home-card contributions from the server and plugins. Text is localized using the Accept-Language header. Component trees are shaped to the X-Ui-Schema-Version header. Authorization is enforced per contribution.

RPC reference: IUiService

Method Path Parameters Response Auth Description
GET /ui/contributions kind (query, UiContributionKind?, optional): Filter by kind.
slot (query, String?, optional): Filter by slot name.		 JSON List<UiContributionInfo> JWT List UI contributions visible to the current user. (listContributions)
POST /ui/dispatchHook event (body, UiHookEvent): The event. JSON List<UiHookHandler> JWT Forward an app-level event (e.g. a shared URL). Returns every contribution offering to handle it. Perform the single action directly or let the user choose. An empty list means no server-side handler. Fall back to native behaviour then. (dispatchHook)
PUT /ui/homeCardOrder contributionIds (query, repeated, List<String>): Pinned contribution ids in display order. JSON UiHomeLayout JWT Persist the order of the current user's pinned home cards. (setHomeCardOrder)
PUT /ui/homeCardPinned/{contributionId} contributionId (path, String): HOME_CARD contribution id.
pinned (query, Boolean): Whether the card should be pinned.		 JSON UiHomeLayout JWT Pin or unpin a home card for the current user. (setHomeCardPinned)
GET /ui/homeCards - JSON UiHomeLayout JWT Home-card layout of the current user, including cards available for pinning. (getHomeCards)
GET /ui/hookHandlers kind (query, UiHookKind?, optional): Only handlers serving this kind. Null lists all. JSON List<UiHookHandlerInfo> JWT List every handler that may offer to take hook events for the current user, without an input. Intake resolvers serve every kind. Contributions list the kinds they declare. Whether a handler accepts a specific event is only known from dispatchHook. (listHookHandlers)
POST /ui/intake items (body, List<IntakeItem>): Items to submit.
resolverId (query, String?, optional): Handler to use, from a previous NEEDS_CHOICE result. Null lets the server decide.		 JSON UiIntakeResult JWT Hand items (links, codes, ids, text) to the server. Unambiguous items are submitted immediately. When several handlers offer, NEEDS_CHOICE returns them and the client calls intake again with the chosen handler's action. Items nobody accepts are returned as rejected. (intake)
POST /ui/invoke/{contributionId} contributionId (path, String): Contribution id.
actionId (query, String): Action id from UiAction.Invoke.
payload (body, UiInvokePayload): Values and context.		 JSON UiInvokeResult JWT Dispatch an action declared by a contribution, with form values and/or action parameters. (invoke)
POST /ui/render/{contributionId} contributionId (path, String): Contribution id.
context (body, UiContext): Host context.		 JSON UiRender JWT Render a single contribution. (render)
POST /ui/renderSlot slot (query, String): Slot name, see UiSlots.
context (body, UiContext): Host context of the slot.		 JSON UiSlotRender JWT Render all contributions registered for a slot that the current user may see, in display order. (renderSlot)
POST /ui/resolveIntake items (body, List<IntakeItem>): Items to resolve. JSON List<UiHookHandler> JWT List the handlers offering to take the items without submitting anything. (resolveIntake)
POST /ui/search/{contributionId} contributionId (path, String): Id of the contribution that rendered the SearchField.
key (query, String): Key of the SearchField.
query (query, String): Text typed by the user.
context (body, UiContext): Host context the contribution was rendered with.		 JSON List<UiOption> JWT Options for a SearchField of a contribution that match the typed query, at most 50. (search)
GET /ui/subscribe/{contributionId} contributionId (path, String): Contribution id.
entityId (query, PlatformUUID?, optional): Host entity id, if the contribution is rendered on an entity screen.		 SSE UiRender JWT Stream re-renders of a contribution. Emits the current render immediately, then on every change. (subscribe)
GET /ui/subscribeLive/{contributionId} contributionId (path, String): Contribution id.
key (query, String): Key of the Live node.
entityId (query, PlatformUUID?, optional): Host entity id, if the contribution is rendered on an entity screen.		 SSE UiLiveUpdate JWT Stream updates for a Live node of a contribution. Subscribe once per Live node while it is on screen. (subscribeLive)
POST /ui/subscribeLiveWithContext/{contributionId} contributionId (path, String): Contribution id.
key (query, String): Key of the Live node.
context (body, UiContext): Host context, the same one passed to render.		 SSE UiLiveUpdate JWT Stream updates for a Live node of a contribution rendered with a full host context, including the params a page was opened with. Subscribe once per Live node while it is on screen. Prefer it over IUiService.subscribeLive, which only carries the entity id. (subscribeLiveWithContext)
POST /ui/subscribeWithContext/{contributionId} contributionId (path, String): Contribution id.
context (body, UiContext): Host context, the same one passed to render.		 SSE UiRender JWT Stream re-renders of a contribution rendered with a full host context, including the params a page was opened with. Emits the current render immediately, then on every change. Prefer it over IUiService.subscribe, which only carries the entity id. (subscribeWithContext)

/userPlaylistBackup — IUserPlaylistBackupService

Personal playlist backup and restoration for individual users.

RPC reference: IUserPlaylistBackupService

Method Path Parameters Response Auth Description
DELETE /userPlaylistBackup/backup fileName (query, String): The name of the backup file. - JWT Delete a personal playlist backup file. (deleteBackup)
POST /userPlaylistBackup/backup - - JWT Create a backup of all playlists owned by the current user. (createBackup)
GET /userPlaylistBackup/backupContent fileName (query, String): The name of the backup file. JSON UserPlaylistBackup? JWT Peek into the contents of a specific user playlist backup. (getBackupContent)
GET /userPlaylistBackup/backups - JSON List<BackupInfo> JWT List all available playlist backup files for the current user. (listBackups)
POST /userPlaylistBackup/restoreBackup fileName (query, String?, optional): Optional name of the backup file. If null, the latest backup is used. - JWT Restore user playlists from a backup file. (restoreBackup)

/userPlaylist — IUserPlaylistService

Management of personal (user-created) playlists.

RPC reference: IUserPlaylistService

Method Path Parameters Response Auth Description
POST /userPlaylist/addAlbumToPlaylist/{id} id (path, PlatformUUID): The playlist unique identifier.
albumId (query, PlatformUUID): The album unique identifier.		 - JWT Add all songs of an album to a user playlist. (addAlbumToPlaylist)
POST /userPlaylist/addPlaylistToPlaylist/{id} id (path, PlatformUUID): The target playlist unique identifier.
sourcePlaylistId (query, PlatformUUID): The source playlist unique identifier.		 - JWT Add all songs of a playlist to a user playlist. (addPlaylistToPlaylist)
POST /userPlaylist/addSongsToPlaylist/{id} id (path, PlatformUUID): The playlist unique identifier.
songIds (query, repeated, List<PlatformUUID>): Collection of song IDs to add.		 - JWT Add songs to a user playlist. (addSongsToPlaylist)
POST /userPlaylist/addToPlaylist/{id} id (path, PlatformUUID): The playlist unique identifier.
songIds (body, List<Pair<Long, PlatformUUID>>): Collection of song IDs and their added timestamps.		 - JWT Add songs to a user playlist. (addToPlaylist)
POST /userPlaylist/addUserPlaylistToPlaylist/{id} id (path, PlatformUUID): The target playlist unique identifier.
sourcePlaylistId (query, PlatformUUID): The source user playlist unique identifier.		 - JWT Add all songs of a user playlist to a user playlist. (addUserPlaylistToPlaylist)
GET /userPlaylist/allPlaylists creator (query, PlatformUUID?, optional): Optional creator ID to filter by.
page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.		 JSON PaginatedResponse<UserPlaylist> JWT Get all user playlists. (allPlaylists)
GET /userPlaylist/byColor creator (query, PlatformUUID?, optional): Optional creator ID to filter by.
page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
color (query, Int): The target color in ARGB format.
range (query, Int, optional): The allowed range (0-255).		 JSON PaginatedResponse<UserPlaylist> JWT Search for user playlists by color. (byColor)
GET /userPlaylist/byId/{id} id (path, PlatformUUID): The playlist unique identifier. JSON UserPlaylist? JWT Get user playlist by ID. (byId)
GET /userPlaylist/byIds ids (query, repeated, List<PlatformUUID>): Collection of playlist IDs. JSON List<UserPlaylist> JWT Get multiple user playlists by their IDs. (byIds)
POST /userPlaylist/orAddPlaylist/{userId} userId (path, PlatformUUID): The user ID who owns the playlist.
customIdentifier (query, String?, optional): Optional unique string identifier from an external source.
playlist (body, InsertablePlaylist): The initial playlist data.		 JSON PlatformUUID JWT Create a new user playlist or retrieve an existing one by a custom identifier. (getOrAddPlaylist)
DELETE /userPlaylist/playlist/{id} id (path, PlatformUUID): The playlist unique identifier. JSON Boolean JWT Delete a user playlist. (delete)
POST /userPlaylist/playlistFromArtists/{userId} userId (path, PlatformUUID): The user ID who owns the playlist.
name (query, String): The name of the playlist.
artistIds (query, repeated, List<PlatformUUID>): Collection of artist IDs.
maxSongsPerArtist (query, Int, optional): Maximum number of songs per artist.
sortStrategy (query, ArtistPlaylistSortStrategy, optional): Sorting strategy.		 JSON PlatformUUID JWT Create a smart playlist based on artists. (createPlaylistFromArtists)
PUT /userPlaylist/playlistImage/{id} id (path, PlatformUUID): The playlist unique identifier.
imageId (query, PlatformUUID?, optional): The image unique identifier.		 JSON Boolean JWT Set the cover image for a user playlist. (setPlaylistImage)
PUT /userPlaylist/public/{id} id (path, PlatformUUID): The playlist unique identifier.
isPublic (query, Boolean): Whether the playlist is public.		 JSON Boolean JWT Make a user playlist public or private. A public playlist can be found and opened by every user, a private one only by its owner and the users it is shared with. Returns false when the playlist does not exist. (setPublic)
GET /userPlaylist/search creator (query, PlatformUUID?, optional): Optional creator ID to filter by.
page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.
query (query, String): The search query.		 JSON PaginatedResponse<UserPlaylist> JWT Search user playlists. (rankedSearch)
DELETE /userPlaylist/share/{id} id (path, PlatformUUID): The playlist unique identifier.
userId (query, PlatformUUID): The unique identifier of the user to remove.		 JSON Boolean JWT Stop sharing a user playlist with a user. The owner can remove any share, and a user can remove their own to leave the playlist. Returns false when the playlist was not shared with that user. (removeShare)
PUT /userPlaylist/share/{id} id (path, PlatformUUID): The playlist unique identifier.
userId (query, PlatformUUID): The unique identifier of the user to share the playlist with.
access (query, PlaylistAccess): What the user may do with the playlist.		 - JWT Share a user playlist with a user, or change the access of a user it is already shared with. Only the owner can do this, and the owner cannot be given a share. (setShare)
GET /userPlaylist/sharedPlaylists page (query, Int, optional): Page index.
pageSize (query, Int, optional): Number of items per page.		 JSON PaginatedResponse<UserPlaylist> JWT Get the user playlists that other users shared with the current user. (sharedPlaylists)
DELETE /userPlaylist/songs/{id} id (path, PlatformUUID): The playlist unique identifier.
songIds (query, repeated, List<PlatformUUID>): Collection of song IDs to remove.		 JSON Int JWT Remove songs from a user playlist. (removeFromPlaylist)
POST /userPlaylist/transferOwnership/{id} id (path, PlatformUUID): The playlist unique identifier.
newOwnerId (query, PlatformUUID): The unique identifier of the user who becomes the owner.		 JSON Boolean JWT Hand a user playlist over to another user. The previous owner keeps write access through a share. Returns false when the playlist or the new owner does not exist or the user already owns the playlist. (transferOwnership)

/user — IUserService

Manages user profiles and identities.

RPC reference: IUserService

Method Path Parameters Response Auth Description
GET /user/allProfiles - JSON List<UserProfile> JWT List the name and avatar of every user on the server, ordered by username. (allProfiles)
GET /user/allUsers - JSON List<User> JWT + Admin List all users on the server. (allUsers)
GET /user/byId/{id} id (path, PlatformUUID): The unique UUID of the user. JSON User? JWT Look up a user by their unique ID. (byId)
GET /user/byUsername username (query, String): The username of the user. JSON User? JWT Look up a user by their username. (byUsername)
PUT /user/capabilities/{id} id (path, PlatformUUID): The UUID of the user.
capabilities (query, repeated, List<UserCapability>): The new list of capabilities.		 - JWT + Admin Update the capabilities for a specific user. (setCapabilities)
PUT /user/displayName name (query, String?, optional): The new display name. - JWT Update the current user's display name. (setDisplayName)
GET /user/me - JSON User JWT Get the profile of the current authenticated user. (me)
PUT /user/profileImage bytes (body, ByteArray): The raw bytes of the image. - JWT Update the current user's avatar. (setProfileImage)
POST /user/user user (body, AuthenticationRequest): The user data.
isAdmin (query, Boolean, optional): Whether the user is an admin.
capabilities (query, repeated, List<UserCapability>, optional): The initial capabilities of the user.		 JSON User? JWT + Admin Create a new user. (createUser)

/import — IImportService

Management of the integrated media importer.

RPC reference: IImportService

Method Path Parameters Response Auth Description
GET /import/allImportServices - JSON List<ImportBackend> JWT Get all available importer backends. (allImportServices)
GET /import/authUrl - JSON String JWT + Admin Get the Tidal OAuth authorization URL. (getAuthUrl)
GET /import/currentImport - JSON ImportQueueEntry? JWT Get the currently active import task. (currentImport)
GET /import/existsByOriginalId/{id} id (path, PrefixedId): The original ID to check.
type (query, Type, optional): The type of content.		 JSON Boolean JWT Check if content with a specific original ID is already present in the library. (existsByOriginalId)
GET /import/finishedImports - JSON List<FinishedImportQueueEntry> JWT Get a list of recently completed or failed import tasks. (finishedImports)
GET /import/importAuthorized - JSON Boolean JWT Check if the importer is authorized. (importAuthorized)
PUT /import/importCredentials backend (body, ImportBackend): The importer backend to configure.
credentials (body, ImporterCredentials): The credentials to supply.		 - JWT + Admin Provide credentials to an importer backend that supports credential injection. (setImportCredentials)
POST /import/importIds ids (query, repeated, List<PrefixedId>): Collection of IDs.
type (query, Type, optional): The type of content (SONG, ALBUM, etc.).
importer (body, ImportBackend?, optional): The importer to use.		 - JWT + IMPORT Queue content for import by its IDs. (importIds)
POST /import/importLogin - SSE String JWT + IMPORT Trigger the OAuth login flow and stream the login URL. (importLogin)
GET /import/importQueue - JSON List<ImportQueueEntry> JWT Get the list of pending import tasks in the queue. (importQueue)
GET /import/importService - JSON ImportBackend JWT Get the currently active importer backend. (getImportService)
PUT /import/importService service (body, ImportBackend): The importer service to use. - JWT + Admin Set the preferred importer backend. (setImportService)
POST /import/importUrls urls (query, repeated, List<String>): Collection of URLs, ISRCs, or UPCs. - JWT + IMPORT Queue content for import. Each entry may be a URL, an ISRC (track), or a UPC (album barcode). Codes are resolved to a supported importer (preferring the default). (importUrls)
GET /import/importerCapabilities - JSON Map<String, Set<ImporterCapability>> JWT Get the capabilities supported by each importer backend, keyed by backend id. (getImporterCapabilities)
GET /import/importerForUrl url (query, String): The URL to check. JSON ImportBackend? JWT Get the appropriate importer backend for a given URL. (getImporterForUrl)
POST /import/killAllChildProcesses - - JWT + Admin Immediately stop all active importer processes. (killAllChildProcesses)
GET /import/logs - SSE LogLine JWT Stream real-time import logs from active processes. (logs)
POST /import/syncFavourites - - JWT + IMPORT Synchronize favorites with the local library. (syncFavourites)
GET /import/syncFavouritesAvailable - JSON Boolean JWT Check if favorite synchronization is available. (syncFavouritesAvailable)
GET /import/tidalSyncAuthorized - JSON Boolean JWT Check if Tidal favorite synchronization is authorized. (tidalSyncAuthorized)
GET /import/tracks query (query, String?, optional): General search query.
title (query, String?, optional): Filter by track title.
artist (query, String?, optional): Filter by artist name.
count (query, Int, optional): Maximum number of results.		 JSON List<ImportSong> JWT Search for tracks directly. (search)

/linkResolver — ILinkResolverService

Find links to a song or album on other streaming platforms.

RPC reference: ILinkResolverService

Method Path Parameters Response Auth Description
GET /linkResolver/resolvePlatformLinks urls (query, repeated, List<String>, optional): Links to the song or album on a streaming platform.
isrc (query, String?, optional): The ISRC of the song.
upc (query, String?, optional): The UPC or EAN barcode of the album.		 JSON List<String> JWT Resolve links to the same song or album on other platforms without touching the library. The ISRC is tried first, then the UPC, then each seed URL in order. Returns an empty list when nothing resolves. (resolvePlatformLinks)

/metadata — IMetadataService

Service for fetching metadata from external sources.

RPC reference: IMetadataService

Method Path Parameters Response Auth Description
GET /metadata/allMetadataTypes features (query, repeated, Set<Feature>, optional): Optional set of features that must be supported by the provider. JSON List<MetadataType> JWT Get all registered metadata providers, optionally filtered by supported features. (allMetadataTypes)
GET /metadata/{type}/albumByBarcode type (path, MetadataType): The metadata provider to use.
barcode (query, String): The barcode.		 JSON Album? JWT Get an album by its barcode. (getAlbumByBarcode)
GET /metadata/{type}/albumByMbId/{mbId} type (path, MetadataType): The metadata provider to use.
mbId (path, PlatformUUID): The MusicBrainz Album (Release) UUID.		 JSON Album? JWT Get an album by its MusicBrainz ID. (getAlbumByMbId)
GET /metadata/{type}/albumExistsById/{albumId} type (path, MetadataType): The metadata provider to use.
albumId (path, String): The external album ID.		 JSON Boolean JWT Check if an album exists by its external ID. (albumExistsById)
GET /metadata/{type}/albumIdByTrackId/{trackId} type (path, MetadataType): The metadata provider to use.
trackId (path, String): The external track ID.		 JSON String? JWT Get the album ID for a given track ID. (getAlbumIdByTrackId)
GET /metadata/{type}/albums type (path, MetadataType): The metadata provider to use.
query (query, String): The search query.
limit (query, Int, optional): Maximum number of results to return.
includeTracks (query, Boolean, optional): Whether to include tracks in the album results.		 JSON List<Album> JWT Search for albums on the specified metadata provider. (searchAlbums)
GET /metadata/{type}/albumsByIds type (path, MetadataType): The metadata provider to use.
albumIds (query, repeated, List<String>): List of external album IDs.		 JSON List<Album> JWT Get multiple albums by their external IDs. (getAlbumsByIds)
GET /metadata/{type}/artistByMbId/{mbId} type (path, MetadataType): The metadata provider to use.
mbId (path, PlatformUUID): The MusicBrainz Artist UUID.		 JSON Artist? JWT Get an artist by their MusicBrainz ID. (getArtistByMbId)
GET /metadata/{type}/artists type (path, MetadataType): The metadata provider to use.
query (query, String): The search query.
limit (query, Int, optional): Maximum number of results to return.		 JSON List<Artist> JWT Search for artists on the specified metadata provider. (searchArtists)
GET /metadata/{type}/artistsByIds type (path, MetadataType): The metadata provider to use.
artistIds (query, repeated, List<String>): List of external artist IDs.		 JSON List<Artist> JWT Get multiple artists by their external IDs. (getArtistsByIds)
GET /metadata/{type}/imageUrlByAlbumId/{albumId} type (path, MetadataType): The metadata provider to use.
albumId (path, String): The external album ID.		 JSON List<Image> JWT Get image URLs for a given album ID. (getImageUrlByAlbumId)
GET /metadata/{type}/imageUrlByAlbumMbId/{mbId} type (path, MetadataType): The metadata provider to use.
mbId (path, PlatformUUID): The MusicBrainz Album (Release) UUID.		 JSON List<Image> JWT Get image URLs for an album by its MusicBrainz ID. (getImageUrlByAlbumMbId)
GET /metadata/{type}/imageUrlByArtistMbId/{mbId} type (path, MetadataType): The metadata provider to use.
mbId (path, PlatformUUID): The MusicBrainz Artist UUID.		 JSON List<Image> JWT Get image URLs for an artist by their MusicBrainz ID. (getImageUrlByArtistMbId)
GET /metadata/{type}/imageUrlByImageId/{imageId} type (path, MetadataType): The metadata provider to use.
imageId (path, PlatformUUID): The image UUID.		 JSON String? JWT Get the URL for a cached image by its ID. (getImageUrlByImageId)
GET /metadata/{type}/imageUrlByTrackMbId/{mbId} type (path, MetadataType): The metadata provider to use.
mbId (path, PlatformUUID): The MusicBrainz Track (Recording) UUID.		 JSON List<Image> JWT Get image URLs for a track by its MusicBrainz ID. (getImageUrlByTrackMbId)
GET /metadata/{type}/imageUrlsByAlbumIds type (path, MetadataType): The metadata provider to use.
albumIds (query, repeated, List<String>): List of external album IDs.		 JSON Map<String, List<Image>> JWT Get image URLs for multiple album IDs. (getImageUrlsByAlbumIds)
GET /metadata/{type}/supportedFeatures type (path, MetadataType): The metadata provider to check. JSON Set<Feature> JWT Get the list of features supported by the specified metadata provider. (getSupportedFeatures)
GET /metadata/{type}/trackById/{trackId} type (path, MetadataType): The metadata provider to use.
trackId (path, String): The external track ID.		 JSON Track? JWT Get a track by its external ID. (getTrackById)
GET /metadata/{type}/trackByIsrc type (path, MetadataType): The metadata provider to use.
isrc (query, String): The ISRC.		 JSON Track? JWT Get a track by its ISRC. (getTrackByIsrc)
GET /metadata/{type}/trackByMbId/{mbId} type (path, MetadataType): The metadata provider to use.
mbId (path, PlatformUUID): The MusicBrainz Track (Recording) UUID.		 JSON Track? JWT Get a track by its MusicBrainz ID. (getTrackByMbId)
GET /metadata/{type}/tracks type (path, MetadataType): The metadata provider to use.
query (query, String): The search query.
limit (query, Int, optional): Maximum number of results to return.		 JSON List<Track> JWT Search for tracks on the specified metadata provider. (search)
GET /metadata/{type}/tracksByIds type (path, MetadataType): The metadata provider to use.
trackIds (query, repeated, List<String>): List of external track IDs.		 JSON List<Track> JWT Get multiple tracks by their external IDs. (getTracksByIds)

/musicBrainz — IMusicBrainzService

Fetch raw metadata records directly from the MusicBrainz database.

RPC reference: IMusicBrainzService

Method Path Parameters Response Auth Description
GET /musicBrainz/artist/{id} id (path, PlatformUUID): The MusicBrainz Artist UUID. JSON MusicBrainzArtist? JWT Retrieve a MusicBrainz Artist record. (getArtist)
GET /musicBrainz/recording title (query, String): The title of the recording.
artists (query, repeated, List<String>): The artists of the recording.		 JSON MusicBrainzRecording? JWT Search for a recording on MusicBrainz. (searchRecording)
GET /musicBrainz/recording/{id} id (path, PlatformUUID): The MusicBrainz Recording UUID. JSON MusicBrainzRecording? JWT Retrieve a MusicBrainz Recording record by its MusicBrainz Recording UUID. (getRecording)
GET /musicBrainz/recordingByIsrc isrc (query, String): The ISRC. JSON MusicBrainzRecording? JWT Retrieve a MusicBrainz Recording record by its ISRC. (getRecordingByIsrc)
GET /musicBrainz/release title (query, String): The title of the release.
artists (query, repeated, List<String>): The artists of the release.		 JSON MusicBrainzRelease? JWT Search for a release (album) on MusicBrainz. (searchRelease)
GET /musicBrainz/release/{id} id (path, PlatformUUID): The MusicBrainz Release UUID. JSON MusicBrainzRelease? JWT Retrieve a MusicBrainz Release record. (getRelease)
GET /musicBrainz/releaseByBarcode barcode (query, String): The barcode (UPC/EAN).
artists (query, repeated, List<String>): The artists of the release.		 JSON MusicBrainzRelease? JWT Search for a release by barcode on MusicBrainz. (searchReleaseByBarcode)
GET /musicBrainz/releaseGroup/{id} id (path, PlatformUUID): The MusicBrainz Release Group UUID. JSON MusicBrainzReleaseGroup? JWT Retrieve a MusicBrainz Release Group record. (getReleaseGroup)
GET /musicBrainz/releasesByReleaseGroup/{id} id (path, PlatformUUID): The MusicBrainz Release Group UUID. JSON List<MusicBrainzRelease> JWT Retrieve all releases in a MusicBrainz Release Group. (getReleasesByReleaseGroup)