Introduction
All urls are using the format http://<host>:<port>/api/v4, example:
http://my.domain.com:8000/api/v4.
All data is returned in JSON format except for images and streams that are returned in binary format.
All calls are using the HTTP GET verb unless it is explicitly mentioned that another verb is used.
All methods except those in the General, Users and Stream categories requires a valid authorization token. See /api/v4/users/login for more information.
General
/api/v4/version
Returns version information from the server hosting the web service.
/api/v4/handshake
Returns 1 if it allows remoting commands. See the remote section below.
Users
/api/v4/users/list
Returns the available users for the active library.
/api/v4/users/login
This call is using the POST verb to validate a user and get an authorization token (if successful).
Input data should be sent in JSON form:
{ "password": "password", "username":"username" }
You should persist the token that is returned from this call so that you can send it in the Authorization header for all coming requests.
api/v4/users/remotetoken
Returns an authorization token to be used for remote controlling only. Avoid to use it in other scenarios since this call will not set the active user. Used to display playlists, favourites, ratings and more.
You should persist the token that is returned from this call so that you can send it in the Authorization header for all incoming requests.
Albums
/api/v4/albums/letters
Returns all available album letters.
/api/v4/albums/letter/{letter}
Returns all albums starting with a specific letter.
/api/v4/albums/favourites
Returns all favourite albums for the logged in user.
/api/v4/albums/year/{year}
Returns all albums for a specific year.
/api/v4/albums/addeddate/{date}
Returns all albums that are added a specific date. The date should be in the form YYYY-MM-DD,
Example: /api/v4/albums/addeddate/2016-01-01
/api/v4/albums/label/{label}
Returns all albums from a specific label.
/api/v4/albums/similar/{albumid}
Find similar albums based on the specific albumId.
Example: /api/v4/albums/similar/1
/api/v4/albums/{albumid}
Return album information for a specific album by albumId.
Example: /api/v4/albums/1
/api/v4/albums/setfavourite/{albumid}
Set a specific album as favourite by albumId.
Example: /api/v4/albums/setfavourite/1
/api/v4/albums/unsetfavourite/{albumid}
Remove a specific album from favourites by albumId.
Example: /api/v4/albums/unsetfavourite/1
/api/v4/albums/search/{expression}
Find specific albums matching the search expression.
Example: /api/v4/albums/search/dark
/api/v4/albums/bydetailid/{trackid}
Get a specific album by a track id.
Example: /api/v4/albums/bydetailid/1
Artists
/api/v4/artists/letters
Returns all available artist letters.
/api/v4/artists/letter/c
Returns all artists starting with a specific letter.
/api/v4/artists/favourites
Returns all favourite albums for the logged in user.
/api/v4/artists/details/{artistid}
Returns artist information for a specific artist by artistId.
Example: /api/v4/artists/details/1
/api/v4/artists/similar/{artistid}
Find similar artists based on the specific artistId.
Example: /api/v4/artists/similar/1
/api/v4/artists/search/{expression}
Find specific artists matching the search expression.
Example: /api/v4/artists/search/john
/api/v4/artists/setfavourite/{artistid}
Set a specific artist as favourite by artistId.
Example: /api/v4/artists/setfavourite/1
/api/v4/artists/unsetfavourite/{artistid}
Remove a specific artist from favourites by artistId.
Example: /api/v4/artists/unsetfavourite/1
Album artists
/api/v4/albumartists/letters
Returns all available album artist letters.
/api/v4/albumartists/letter/{letter}
Returns all album artists starting with a specific letter.
Genres
/api/v4/genres/
Returns all distinct genres from the library.
Labels
/api/v4/labels/letters
Returns all distinct labels from the library.
/api/v4/labels/letter/{letter}
Returns all labels starting with a specific letter.
Playlists
/api/v4/playlists/
Returns all playlists.
/api/v4/smartplaylists/
Returns all smart playlists.
/api/v4/playlist/add/{playlistid}/{trackid}
Adds a new track to a specific playlist.
Example: /api/v4/playlist/add/1/1
/api/v4/playlist/addalbum/{playlistid}/{albumid}
Adds all tracks for an album to a specific playlist.
Example: /api/v4/playlist/addalbum/1/2
Ratings
/api/v4/ratings/
Returns all distinct ratings
Years
/api/v4/years/
Returns all distinct release years from the library.
/api/v4/years/added/
Returns all distinct release years based on added date.
/api/v4/years/added/{year}
Returns all distinct added months for a specific year.
Example: /api/v4/years/added/2016
/api/v4/years/added/{year}/{month}
Returns all distinct added dates for a specific year and month.
Example: /api/v4/years/added/2016/1
/api/v4/years/played/
Returns all distinct release years based on played date.
/api/v4/years/played/{year}
Returns all distinct played months for a specific year.
Example: /api/v4/years/played/2016
/api/v4/years/played/{year}/{month}
Returns all distinct played dates for a specific year and month.
Example: /api/v4/years/played/2016/1
Tracks
/api/v4/tracks/playlist/{playlistid}
Returns all tracks for a specific playlist by playlistId.
/api/v4/tracks/favourites
Returns all favourite tracks for the current user.
/api/v4/tracks/similar/{trackid}
Returns similar tracks based on the trackId input parameter.
/api/v4/tracks/played/{date}
Returnes all tracks played for a specific date. Date is in the form YYYY-MM-DD.
Example: /api/v4/tracks/played/2016-01-01
/api/v4/tracks/album/{albumid}
Returns all tracks for a specific album by albumId.
/api/v4/tracks/genre/{genre}
Returns all tracks for a specific genre.
Example: /api/v4/tracks/genre/house
/api/v4/tracks/{trackid}
Returns a single track based on trackId.
Example: /api/v4/tracks/1
/api/v4/tracks/smartplaylist/{smartplaylistid}
Returns the tracks for a smart playlist by smartplaylistId.
Example: /api/v4/tracks/smartplaylist/1
/api/v4/tracks/rating/{rating}
Returns all tracks containing a specific rating.
See the appendix for a list of available rating values.
/api/v4/tracks/lyrics/{trackid}
Returns the lyrics for a specific track by trackId.
/api/v4/tracks/search/{expression}
Returns the tracks matching a specific search expression.
Example: /api/v4/tracks/search/freed
/api/v4/tracks/setrating/{trackid}/{rating}
Sets the rating for a specific track by trackId.
See the appendix for a list of valid ratings.
/api/v4/tracks/setfavourite/{trackid}
Set a specific track as a favourite by trackId.
/api/v4/tracks/unsetfavourite/{trackid}
Removes a track from favourites based on trackId.
/api/v4/tracks/updatelastfm/{trackid}
Sends an Now playing notification to Last.fm by trackId.
Requires that Last.fm is enabled.
/api/v4/tracks/posttolastfm/{trackid}
Posts a scrobble for the specific track to Last.fm by trackId.
Requires that Last.fm is enabled.
/api/v4/tracks/updateplaycounter/{trackid}
Increases the play counter for a track by trackId.
Stream
/api/v4/stream/{trackid}
Return a binary stream for a specific track by trackId.
/api/v4/subtrackstream/{trackid}
Returns a subtrack as a specific stream by its trackId.
The subtrack will be extracted and transcoded in runtime.
Images
Note: None of these calls requires an auth-token.
/api/v4/images/album/{albumid}
Returns the album image for a specific album by albumId.
Example: /api/v4/images/album/1
Return type: Binary
/api/v4/images/album/{albumid}/{width}/{height}
Returns the album image for a specific album with the specific dimensions.
Example: /api/v4/images/album/3/96/96
Return type: Binary
/api/v4/images/albumbytrack/{trackid}
Returns the album image for an album, specified via it’s track id.
Example: /api/v4/images/albumbytrack/3
Return type: Binary
/api/v4/images/artist/{artistid}
Returns the artist image for a specific artist by artistId.
Example: /api/v4/images/artist/1
Return type: Binary
/api/v4/images/artist/{artistid}/{width}/{height}
Returns the artist image for a specific artist with the specific dimensions.
Example: /api/v4/images/artist/3/96/96
Return type: Binary
Remote
/api/v4/remote/playqueue
Returns all tracks in the active play queue.
/api/v4/remote/playqueue/activeindex
Returns the active index of the play queue.
/api/v4/remote/player/state
Returns the current player state information.
/api/v4/remote/player/nowplayinginfo
Returns information about the currently playing track.
/api/v4/remote/player/play
Starts playback in Neon.
/api/v4/remote/player/pause
Pause/unpase playback in Neon.
/api/v4/remote/player/next
Change to next track in the play queue.
/api/v4/remote/player/previous
Change to the previous track in the play queue.
/api/v4/remote/player/getposition
Returns the current position of the playing track.
/api/v4/remote/player/setposition/{position}
Set the position of the currently playing track.
/api/v4/remote/player/getvolume
Returns the current volume in the range 0-255.
/api/v4/remote/player/setvolume/{volume}
Set the volume in the range 0-255.
/api/v4/remote/playqueue/play/{index}
Play a specific track by index in the play queue. The indexes are zero-based.
/api/v4/remote/playqueue/clear
Clear the play queue.
/api/v4/remote/album/play/{albumid}
Enqueues and plays a specific album by albumId to the play queue.
/api/v4/remote/album/enqueuenext/{albumid}
Enqueues a specific album by albumId next in the play queue.
/api/v4/remote/album/enqueuelast/{albumid}
Enqueues a specific album by albumId last in the play queue.
/api/v4/remote/playlist/play/{playlistid}
Enqueues and plays a specific playlist by playlistId to the play queue.
/api/v4/remote/playlist/enqueuenext/{playlistid}
Enqueues a specific playlist by playlistId next in the play queue.
/api/v4/remote/playlist/enqueuelast/{playlistid}
Enqueues a specific playlist by playlistId last in the play queue.
/api/v4/remote/smartplaylist/play/{smartplaylistid}
Enqueues and plays a specific smart playlist by smartplaylistId to the play queue.
/api/v4/remote/smartplaylist/enqueuenext/{smartplaylistid}
Enqueues a specific smart playlist by smartplaylistId next in the play queue.
/api/v4/remote/smartplaylist/enqueuelast/{smartplaylistid}
Enqueues a specific smart playlist by smartplaylistId lastin the play queue.
/api/v4/remote/track/play/{trackid}
Play a specific track by trackId.
/api/v4/remote/track/enqueuenext/{trackid}
Enqueue a specific track next in the play queue by trackId.
/api/v4/remote/track/enqueuelast/{trackid}
Enqueue a specific track last in the play queue by trackId.
/api/v4/remote/track/addtoplaylist/{playlistid}/{trackid}
Add a specific track by trackId to a specific playlist by playlistId.
Example: /api/v4/remote/track/addtoplaylist/10/2
/api/v4/remote/album/addtoplaylist/{playlistid}/{trackid}
Add a specific album by albumId to a specific playlist by playlistId.
Example: /api/v4/remote/album/addtoplaylist/10/2
Appendix
Rating values
To apply a rating for a specific file you need to use the mapping table below.
For example, if you would like to set rating to 3.5 stars, you will need to send the value 178.
- 5 stars - 255
- 4.5 stars - 229
- 4 stars - 208
- 3.5 stars - 178
- 3 stars - 153
- 2.5 stars - 127
- 2 stars - 102
- 1.5 star - 76
- 1 star - 51
- 0.5 stars - 25
- No rating - 0