Endpoints

OpenSubsonic base endpoints

OpenSubsonic is a specification with a long history, which often has multiple different ways to do the same thing. In general, when there are multiple versions of an endpoint (search, search2, search3, etc.) the higher number is the “better” one, and that’s the one you should try first.

We also use the Recommended column in the table below to indicate which endpoints we think are best to use overall, especially if you are building a new player app. This advice generally maps to how Radiccio works when acting as an OpenSubsonic player-client. Be advised that non-recommended endpoints are provided for legacy compatibility only, and may have slower performance and/or missing data compared to the recommended endpoints.

Endpoint Available in Radiccio Server Recommended Anonymous Access Notes
addChatMessage No      
changePassword No      
createBookmark No      
createInternetRadioStation No      
createPlaylist Yes Yes No Playlists in Radiccio belong to a specific music folder, and all songs must also belong to that same music folder. If the user attempts to create a playlist that mixes songs from different music folders, it will fail with an error.

By default, new playlists are saved as an M3U file in a folder named “Playlists” in the music folder that the songs belong to.

When updating an existing playlist, the existing location and filename will be used.

If the user attempts to create a playlist with a filename that already exists, it will fail with an error.

For best results, try to avoid creating a playlist with zero items. Instead, ask the user to add some items before calling createPlaylist. For compatibility, Radiccio does permit creating playlists with zero items; however, because Radiccio does not know which music folder the playlist should belong to, it creates it in a temporary holding area. When items are added, the playlist is then moved to the correct music folder. This process presents several likely points of failure that would not happen otherwise, so it is best to avoid it by always providing at least one item when creating a playlist, if possible.
createPodcastChannel No      
createShare No      
createUser No      
deleteBookmark No      
deleteInternetRadioStation No      
deletePlaylist Yes Yes No Playlist will be moved to the Trash, where the user can retrieve it (using macOS Finder) in case of accidental deletion, as long as the Trash has not been emptied yet.
deletePodcastChannel No      
deletePodcastEpisode No      
deleteShare No      
deleteUser No      
download Yes Yes Yes  
downloadPodcastEpisode No      
getAlbum Yes Yes Yes  
getAlbumInfo Yes No Yes Provided only to avoid user-facing errors. Radiccio does not have any data relevant to this endpoint, so this always returns an empty object.
getAlbumInfo2 Yes No Yes Provided only to avoid user-facing errors. Radiccio does not have any data relevant to this endpoint, so this always returns an empty object.
getAlbumList Yes No Yes† Use getAlbumList2 instead if possible.

fromYear and toYear are only used for sorting purposes, not for filtering results.

type parameter values highest and genre are not supported and will be ignored.

† Anonymous users are not allowed to use these type values: frequent, highest, recent
getAlbumList2 Yes Yes Yes† fromYear and toYear are only used for sorting purposes, not for filtering results.

type parameter values highest and genre are not supported and will be ignored.

† Anonymous users are not allowed to use these type values: frequent, highest, recent
getArtist Yes Yes Yes  
getArtistInfo Yes No Yes Provided only to avoid user-facing errors. Radiccio does not have any data relevant to this endpoint, so this always returns an empty object.
getArtistInfo2 Yes No Yes Provided only to avoid user-facing errors. Radiccio does not have any data relevant to this endpoint, so this always returns an empty object.
getArtists Yes Yes Yes  
getAvatar No      
getBookmarks No      
getCaptions No      
getChatMessages No      
getCoverArt Yes Yes Yes  
getGenres No      
getIndexes Yes Only for use with folder browsing Yes ifModifiedSince is ignored.

lastModified is always 0.
shortcut is not provided.

This is used to list folders and files at the root level of the music folder. It is not recommended to use this for browsing artists or albums.

Despite the use of the key artist as required by the spec, this actually refers to folders, not artists. This is an idiosyncrasy due to the folder-based nature of the original spec.

The behavior of Radiccio Server described here is consistent with other modern OpenSubsonic servers that implement true folder browsing, like Gonic and LMS. Note that Navidrome does not have any API for actual folder contents, and instead returns a simulated structure derived from file metadata; Radiccio Server follows the Gonic and LMS approach, rather than the Navidrome approach.
getInternetRadioStations No      
getLicense Yes Yes No Like the original Subsonic, Radiccio Server requires a paid subscription in order to function (a free trial is available). When the subscription or trial expires, the server will continue running, but all endpoints other than getLicense will return error 60.

The property valid indicates whether the subscription or trial is active (true or false).

email always returns the Radiccio customer support email address (not printed here to avoid spam).

licenseExpires will be null if the subscription has already expired, or a future date if the subscription is valid. In the case of a one-time purchase, licenseExpires will be a date which is a very large number years in the future (equivalent to Swift Date.distantFuture).

If the user is currently in a free trial, trialExpires will be the same value as licenseExpires. Otherwise, it will be null.

Some users have automatic renewal configured. The response does not indicate whether or not this is the case.
getLyrics No      
getMusicDirectory Yes Only for use with folder browsing Yes This is used to list folders and files beyond the root level. It is not recommended to use this for browsing artists or albums.
getMusicFolders Yes Yes Yes Each “music folder” maps to what is often called a “library”, or in Radiccio terminology, an “On My Mac” source.
getNewestPodcasts No      
getNowPlaying No      
getOpenSubsonicExtensions Yes Yes Yes In accordance with the OpenSubsonic spec, this endpoint is the only endpoint that does not require any authentication parameters (u, s, t, or apiKey). This is useful so that you can discover if the server implements the apiKey extension (which it does, but this is how you should check for it).
getPlaylist Yes Yes Yes  
getPlaylists Yes Yes Yes username parameter is ignored because Radiccio is a single-user system
getPlayQueue No      
getPodcasts No      
getRandomSongs Yes Yes Yes  
getScanStatus No      
getShares No      
getSimilarSongs No      
getSimilarSongs2 No      
getSong Yes Yes Yes  
getSongsByGenre No      
getStarred Yes No No Use getStarred2 instead if possible
getStarred2 Yes Yes No Referred to in Radiccio’s UI as “favorites”
getTopSongs No      
getTranscodeDecision No      
getTranscodeStream No      
getUser Yes Yes Yes Note that you can use the tokenInfo endpoint to get the current username.
getUsers Yes Yes No If anonymous access is enabled, will return two users: admin and anonymous. Otherwise, only admin.
getVideoInfo No      
getVideos No      
hls No     Most other OpenSubsonic servers also do not implement this.
jukeboxControl No      
ping Yes Yes Yes In accordance with the OpenSubsonic spec, this endpoint requires authentication parameters like every other endpoint (except getOpenSubsonicExtensions). Therefore, one useful purpose of ping is to test the user’s authentication credentials to see if they are working; it will fail with an appropriate error if not.
refreshPodcasts No      
savePlayQueue No      
scrobble Yes Yes No  
search No     Spec says this is deprecated, and other servers have dropped it already
search2 Yes No Yes† Use search3 instead if possible

† Anonymous users are not allowed to use these type values: frequent, highest, recent
search3 Yes Yes Yes† Accepts optional parameters type, fromYear and toYear for sorting albums. These parameters work the same as in getAlbumList2. Via search3AlbumSort extension.

When query is not an empty string and sorting parameters are not specified, the results are ordered by FTS5 “ranking” algorithm, which tries to put best matches first.

† Anonymous users are not allowed to use these type values: frequent, highest, recent
setRating No     Check for the unavailable.userRatings extension before calling this endpoint. The presence of this extension means the endpoint is not available.
star Yes Yes No Referred to in Radiccio’s UI as “favorite”
startScan No      
stream Yes Yes Yes maxBitRate and format are not supported and will be ignored. The original audio is always returned. This behavior can be detected by presence of the unavailable.transcoding extension.
unstar Yes Yes No Referred to in Radiccio’s UI as “unfavorite”
updateInternetRadioStation No      
updatePlaylist Yes Yes No comment is not supported and will be ignored.
public is not supported and will be ignored; Radiccio is a single-user system, and all playlists are always visible.

Playlists in Radiccio belong to a specific music folder, and all songs must also belong to that same music folder. If you attempt to update a playlist so that it mixes songs from different music folders, it will fail with an error.

Renaming the playlist does not rename the M3U file, instead it updates the name in the EXTM3U #PLAYLIST: value and in the database.
updateShare No      
updateUser No      

Base endpoints that are not implemented by Radiccio Server will return error code 326471. See the error codes page for more info.

OpenSubsonic extension endpoints

Radiccio Server implements all of the below extension endpoints. Endpoints belonging to extensions which Radiccio Server does not implement are not listed here.

Endpoint Extension Recommended Anonymous Access Notes
tokenInfo apiKeyAuthentication Yes Yes Currently, the username is anonymous if using anonymous auth; admin otherwise. This behavior may change in the future, so do not assume this; always call this endpoint and use the returned value.

Remember, you should be checking the list of extensions with getOpenSubsonicExtensions before you call an extension endpoint. Radiccio returns HTTP 404 for unimplemented extension endpoints.

Radiccio endpoints

Each of these endpoints is associated with a vendor-prefixed extension. See the extensions page.

NOTE: Radiccio endpoints are available in JSON only, not XML. When calling these endpoints, you must pass f=json or the server will return error 3264102.

radiccio/getPinned

Similar to starred2, but returns items with pinned status.

Anonymous access: No

Parameters

Parameter Req. Default Notes
musicFolderId No   Only return results from music folder with the given ID. See getMusicFolders.

Although not required, you are strongly encouraged to provide this.

Example 

http://your-server/rest/radiccio/getPinned?musicFolderId=3264&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Response 

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "Radiccio Server",
    "serverVersion": "1.4 (33)",
    "openSubsonic": true,
    "pinned": {
      "artist": [
        {
          "id": "37ec820ca7193e17040c98f7da7c4b51",
          "name": "2 Mello",
          "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
          "albumCount": 1,
          "userRating": 5,
          "artistImageUrl": "https://demo.org/image.jpg",
		  "radiccio": {
		    "pinned": true
		  }
        }
      ],
      "album": [
        {
          "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
          "name": "8-bit lagerfeuer",
          "artist": "pornophonique",
          "year": 2007,
          "coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
          "duration": 1954,
          "playCount": 97,
          "genre": "Hip-Hop",
          "created": "2023-03-10T02:19:35.784818075Z",
          "artistId": "91c3901ac465b9efc439e4be4270c2b6",
          "songCount": 8,
		  "radiccio": {
		    "pinned": true
		  }
        }
      ]
    }
  }
}
Field Type Req. OpenS. Details
pinned RadiccioPinnedResultSet Yes   A pinned entity which contains artist and album entities

radiccio/getRecentlyPlayedArtists

Returns a list of artists that the user has played recently, ordered by most recent first.

Anonymous access: No

Parameters

Parameter Req. Default Notes
musicFolderId No   Only return results from music folder with the given ID. See getMusicFolders.

Although not required, you are strongly encouraged to provide this.

Example 

http://your-server/rest/radiccio/getRecentlyPlayedArtists?musicFolderId=3264&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Response 

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "Radiccio Server",
    "serverVersion": "1.4 (33)",
    "openSubsonic": true,
    "recentlyPlayedArtists": {
      "artist": [
        {
          "id": "37ec820ca7193e17040c98f7da7c4b51",
          "name": "2 Mello",
          "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
          "albumCount": 1,
          "userRating": 5,
          "artistImageUrl": "https://demo.org/image.jpg"
        }
      ]
    }
  }
}
Field Type Req. OpenS. Details
recentlyPlayedArtists RadiccioRecentlyPlayedArtistsResultSet Yes   An entity which contains artist entities

radiccio/searchPlaylists

The base search endpoints don’t provide a way to search playlists, so we provide a new endpoint to do so.

Anonymous access: Yes

Parameters

Parameter Req. Default Notes
count No all Maximum number of playlists to return.
offset No 0 Search result offset, used for paging. Has no effect if count is all.
query No   User-entered text to search for.

If not provided, all playlist results will be returned. We don’t recommend using it this way (use getPlaylists instead), but it works this way to ensure consistent behavior with the search3 endpoint.
musicFolderId No   Only return results from music folder with the given ID. See getMusicFolders.

Although not required, you are strongly encouraged to provide this. Performance may be very slow otherwise.

Example 

http://your-server/rest/radiccio/searchPlaylists?query=dance&count=20&offset=40u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Response 

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "Radiccio Server",
    "serverVersion": "1.4 (33)",
    "openSubsonic": true,
    "searchPlaylists": {
      "playlist": [
        {
          "id": "800000003",
          "name": "random - admin - private (admin)",
          "owner": "admin",
          "public": false,
          "created": "2021-02-23T04:35:38+00:00",
          "changed": "2021-02-23T04:35:38+00:00",
          "songCount": 43,
          "duration": 17875
        },
        {
          "id": "800000002",
          "name": "random - admin - public (admin)",
          "owner": "admin",
          "public": true,
          "created": "2021-02-23T04:34:56+00:00",
          "changed": "2021-02-23T04:34:56+00:00",
          "songCount": 43,
          "duration": 17786
        }
      ]
    }
  }
}
Field Type Req. OpenS. Details
searchPlaylists playlists Yes   The playlists

radiccio/setPinned

Allows you to change the pinned status of an album or artist. (Songs, playlists and other types of entities are not supported.)

Anonymous access: No

Parameters

Parameter Req. Default Notes
id Yes   The ID of an album or artist
value Yes   true or false

Example 

http://your-server/rest/radiccio/setPinned?id=123&value=true&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Response

An empty subsonic-response element on success.

radiccio/setAutoSkip

Allows you to change the auto skip status of an song or album. (Artists, playlists and other types of entities are not supported.)

Anonymous access: No

Parameters

Parameter Req. Default Notes
id Yes   The ID of a song or album
value Yes   true or false

Example 

http://your-server/rest/radiccio/setAutoSkip?id=123&value=false&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Response

An empty subsonic-response element on success.

radiccio/journalEntries

Returns a list of all journal entries for a music folder.

Anonymous access: No

Parameters

Parameter Req. Default Notes
musicFolderId Yes   The ID of a music folder from getMusicFolders

Response

Field Type Req. OpenS. Details
journalEntries RadiccioJournalEntryResultSet Yes   Journal entries result set

radiccio/createJournalEntry

Creates a new journal entry.

Anonymous access: No

Parameters

Parameter Req. Default Notes
songId Either songId or albumId is required   ID of a song
albumId Either songId or albumId is required   ID of an album
enjoyment At least one of enjoyment, mood, or notes is required   JSON-encoded RadiccioEnjoyment object
mood At least one of enjoyment, mood, or notes is required   JSON-encoded RadiccioMood object
notes At least one of enjoyment, mood, or notes is required   string

Response

An empty subsonic-response element on success.

radiccio/deleteJournalEntry

Deletes a specified journal entry.

Anonymous access: No

Parameters

Parameter Req. Default Notes
id Yes   ID of the journal entry to delete

Response

An empty subsonic-response element on success.

This page was last updated: May 19, 2026

Every word on this web site was written by human hand.

Copyright © 2026 Crispy Crunchy Computerware LLC
Trademarks are property of their respective owners.
Powered by Just The Docs