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.

How to use

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

Implemented commands

rescan
Intention Rescans the complete library
URI /api/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/rescan
rescanFileOrFolder
Intention Rescans a partial subtree of the file system.
URI /api/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/rescanFileOrFolder

HTTP return codes

204 success
401 invalid api key
503 external api is not enabled. Set a api_key in UMS.conf with a length of 12 or more chars

Revision #24
Created Wed, Apr 14, 2021 7:09 AM by ikrahne
Updated Thu, Apr 15, 2021 5:14 AM by ikrahne