External API

The external API enables programs to access or trigger UMS functionalities with a HTTP call.

How to enable the external API

Edit UMS.conf and configure an api_key like this

api_key = secret_password

The secret_password must have a minimum of 12 chars.

API usage

If the external API is enabled, the API is accessible with a POST call to /api/COMMAND

Folder Scanning

rescan
Intention Rescans the complete library
URI /api/folderscanner/rescan
POST BODY NONE
POST BODY example / description This command needs no body content
Available since 10.4.2

Attention: This can be slow for large libraries

Example:

curl -w "%{http_code}\n" -H "api-key: secret_password" http://localhost:5001/api/folderscanner/rescan
rescanFileOrFolder
Intention Rescans a partial subtree of the file system.
URI /api/folderscanner/rescanFileOrFolder
POST BODY PATH_TO_SCAN
POST BODY example / description example: "/music/pop/Madonna". Path must be the root or a subfolder of a shared path.
Available since 10.4.2

Example:

curl -d "PATH_TO_SCAN" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/folderscanner/rescanFileOrFolder

Liking Music (albums and songs)

like song

Song will be marked as liked.

Intention Like a song identified by musicBrainz trackId
URI

/api/like/likesong

POST BODY musicBrainz_trackID
POST BODY example / description

b8695995-45e9-405d-b4aa-e50e8760fe25

Available since 10.20

Example:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/likesong

dislike song

Song will not be disliked

Intention Dislike a song identified by musicBrainz trackId
URI

/api/like/dislikesong

POST BODY musicBrainz_trackID
POST BODY example / description

b8695995-45e9-405d-b4aa-e50e8760fe25

Available since 10.20

Example:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/dislikesong

is song liked

Check if song is liked.

Intention Check if song is liked identified by musicBrainz trackId
URI

/api/like/issongliked

POST BODY musicBrainz_trackID
POST BODY example / description

b8695995-45e9-405d-b4aa-e50e8760fe25

RESPONSE BODY TRUE or FALSE
Available since 10.20

Example:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/issongliked

This call adds the liked attribute of the album identified by musicbrainz release-id 1e0eee38-a9f6-49bf-84d0-45d0647799af.

like album

Set album like state to true.

Intention Likes an album identified by musicBrainz releaseID
URI

/api/like/likealbum

POST BODY musicBrainz_releaseID
POST BODY example / description

1e0eee38-a9f6-49bf-84d0-45d0647799af

Available since 10.20

Example:

curl -d "1e0eee38-a9f6-49bf-84d0-45d0647799af" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/likealbum

dislike album

Remove album like state.

Intention Dislike a song identified by musicBrainz releaseID
URI

/api/like/dislikealbum

POST BODY musicBrainz_releaseID
POST BODY example / description

1e0eee38-a9f6-49bf-84d0-45d0647799af

Available since 10.20

Example:

curl -d "1e0eee38-a9f6-49bf-84d0-45d0647799af" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/dislikealbum

This call removed the liked attribute of the album identified by musicbrainz release-id 1e0eee38-a9f6-49bf-84d0-45d0647799af.

is album liked

Check album like state.

Intention Check if album is liked identified by musicBrainz releaseID
URI

/api/like/isalbumliked

POST BODY musicBrainz_releaseID
POST BODY example / description

1e0eee38-a9f6-49bf-84d0-45d0647799af

RESPONSE BODY "TRUE" or "FALSE"
Available since 10.20

Example:

curl -d "1e0eee38-a9f6-49bf-84d0-45d0647799af" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/like/isalbumliked

This call checks if the album identified by musicbrainz release-id 1e0eee38-a9f6-49bf-84d0-45d0647799af is liked.

Rating

The rating API is responsible for rating songs. Rating information is saved in the internal database (cache enabled) and optionally in the file itself. If audio_update_rating_tag = true is set in UMS.conf the IDv3 rating field also being updated in the song file (if the songs file format is supported).

While browsing the content directory server, MusicBrainzTrackID (if available) and audiotrackID are delivered as `desc` metadata within the DIDL element.

set rating

Intention Set rating in stars (0 - 5) on a song identified by musicBrainz trackId
URI

/api/rating/setrating

POST BODY musicbrainzTrackId/stars
POST BODY example / description

b8695995-45e9-405d-b4aa-e50e8760fe25/3

Available since 10.20

Example:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25/3" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/setrating

This call sets the user rating of all songs identified by the musicbrainz track-id b8695995-45e9-405d-b4aa-e50e8760fe25 to 3.

get rating

Reads song rating from database

Intention Get song rating in stars (0 - 5) by musicBrainz trackID. Response body contains the rating information.
URI

/api/rating/getrating  

POST BODY musicbrainzTrackId
POST BODY example / description

b8695995-45e9-405d-b4aa-e50e8760fe25

RESPONSE BODY example 3
Available since 10.20

Example:

curl -d "b8695995-45e9-405d-b4aa-e50e8760fe25" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/getrating

This call reads the user rating of a song identified by the musicbrainz track-id b8695995-45e9-405d-b4aa-e50e8760fe25.

set rating by audiotrack id

Intention Set rating in stars (0 - 5) on a song identified by UMS internal audiotrackID
URI

/api/rating/setRatingByAudiotrackId

POST BODY trackID/stars
POST BODY example / description

32

Available since 11.0

Example:

curl -d "32/3" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/setrating

This call sets songs user rating identified by audiotrack id 32 to 3.

get rating by audiotrack id

Reads song rating from database

Intention Get song rating in stars (0 - 5) by UMS internal audiotrackID. Response body contains the rating information.
URI

/api/rating/getRatingByAudiotrackId

POST BODY trackId
POST BODY example / description

32

RESPONSE BODY example 3
Available since 11.0

Example:

curl -d "32" -w "%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/rating/getRatingByAudiotrackId

This call reads the user rating of a song identified by UMS audiotrack-id 32.

Backup / Restore

User managed "liked album" entries can be backed up into a profile-directory subfolder named `database_backup`. The filename is `MUSIC_BRAINZ_RELEASE_LIKE`. In case UMS database gets deleted, just call restore.

backup liked albums

Backup table `MUSIC_BRAINZ_RELEASE_LIKE` to filesystem

Intention backup liked songs to filesystem
URI /api/like/backupLikedAlbums
REQUEST TYPE GET
RESPONSE BODY OK or error message 
Available since 10.20

Example:

curl -w "%{http_code}\n" -H "api-key: secret_password" -X GET http://localhost:5001/api/like/backupLikedAlbums

This call will create a backup file containing liked albums.

restore liked albums

Restores table `MUSIC_BRAINZ_RELEASE_LIKE` from filesystem

Intention restore liked songs from backup file
URI /api/like/restoreLikedAlbums
REQUEST TYPE GET
RESPONSE BODY OK or error message 
Available since 10.20

Example:

curl -w "%{http_code}\n" -H "api-key: secret_password" -X GET http://localhost:5001/api/like/restoreLikedAlbums

This call restores the backup file.

Playlist

enable service

Edit UMS.conf and configure a managed playlist folder by setting 

managed_playlist_folder = PATH_TO_PLAYLIST_FOLDER

for enabling this service. By default this service is disabled. The playlist folder path should be located beneath a configured shared folders path for playlist changed made by this API to be visible by UMS.

list all playlists

Read available playlists. These playlist names have to be used for subsequent calls to add or remove songs.

Intention Delivers all supported (m3u, m3u8 and pls) and available playlists from configured folder. Besides playlist name, the playlists `playlistId` is 
URI

/api/playlist/getAllPlaylists

REQUEST TYPE

GET

RESPONSE BODY JSON array of playlist names
RESPONSE BODY example

["Pop","Jazz","Classic"]

Available since 11.0

Example:

curl -d "" -w "\n%{http_code}\n" -H "api-key: secret_password" -X GET http://localhost:5001/api/playlist/getAllPlaylists

This call will list list all available playlist.

list server accessible playlists

These are all playlist known to UMS (database/cache enabled). These playlist names have to be used for subsequent calls to add or remove songs. The playlist ID can be used to navigate directly to the playlist by browsing the `objectId` `$DBID$PLAYLIST$` concat databaseId.

Intention Delivers all supported (m3u, m3u8 and pls) and available playlists from configured folder
URI

`/api/playlist/getserverplaylists`

REQUEST TYPE

GET

RESPONSE BODY JSON array of playlist names
RESPONSE BODY example

[{"playlistName":"Jazz","playlistId":5},{"playlistName":"Charts","playlistId":343}]

Available since dev branch

Example:

curl -d "" -w "\n%{http_code}\n" -H "api-key: secret_password" -X GET http://localhost:5001/api/playlist/getserverplaylists

This call will list list all available playlist accessible by UMS.

adding songs to playlists

The required audiotrackid is delivered during UPnP browse requests and can be extracted from the DIDL response attribute descMetadata

<ums-tags>
[...]
	<audiotrackid>ID</audiotrackid>
[...]
</ums-tags>

Intention Add song to playlist
URI

/api/playlist/addSongToPlaylist

REQUEST TYPE

POST

POST BODY

audiotrackid/PLAYLIST

POST BODY example / description

123/Pop

RESPONSE BODY NONE
Available since 11.0

Example:

curl -d "123/Pop" -w "\n%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/playlist/addSongToPlaylist

This adds the song with the ID 123 to the playlist Pop.

removing songs from playlists

The required audiotrackid is delivered during UPnP browse requests and can be extracted from the DIDL response attribute descMetadata

<ums-tags>
[...]
	<audiotrackid>ID</audiotrackid>
[...]
</ums-tags>

Intention Remove song from playlist
URI

/api/playlist/removeSongFromPlaylist

REQUEST TYPE

POST

POST BODY

audiotrackid/PLAYLIST

POST BODY example / description

123/Pop

RESPONSE BODY NONE
Available since 11.0

Example:

curl -d "123/Pop" -w "\n%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/playlist/removeSongFromPlaylist

This removes the song with the ID 123 from the playlist Pop.

create new playlists

Playlist name should be provided without any path and without file extensions. 

Intention Creating new playlists in managed playlist folder
URI

/api/playlist/createPlaylist

REQUEST TYPE

POST

POST BODY

PLAYLIST_NAME

POST BODY example / description

Contemporary

RESPONSE BODY NONE
Available since 11.0

Example:

curl -d "Contemporary" -w "\n%{http_code}\n" -H "api-key: secret_password" -X POST http://localhost:5001/api/playlist/createPlaylist

This call creates a new playlist file named Contemporary.m3u8 in the managed playlist folder.

Java code example

This code snippet shows how to use the API with okhttp3 library.

import nextcp.dto.Config;
import nextcp.dto.UmsServerApiKey;
import okhttp3.Call;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

[...]

    public String executeCall() throws IOException
    {
        String postBody = "1e0eee38-a9f6-49bf-84d0-45d0647799af";
        String apiKey = "secret_password";
        RequestBody body = RequestBody.create(postBody, MediaType.parse("application/text"));
        String requestUrl = "http://127.0.0.1:5001/api/like/likealbum";
        Request request = new Request.Builder().url(requestUrl).addHeader("api-key", apiKey).post(body).build();
        Call call = okClient.newCall(request);
        Response response = call.execute();
        return response.body().string();
    }

HTTP return codes

200 OK
204 success if no content is supposed to be returned
401 invalid api key
404 requested object cannot be found
417 API request failed
503 external api is not enabled. Set a api_key in UMS.conf with a length of 12 or more character