For APIv3, the Swagger documentation offers interactive curl examples:
Please use the Swagger docs to explore the APIv3:
https://download-unimus.netcore.software/api-v3-preview/
For APIv2 curl examples, please see below.
The curl examples will use this format:
curl -sS \ -H 'Authorization: Bearer <token>' \ -d '<data>' \ 'http://<unimus-address>:8085/api/v2/<API-path>' | json_pp |
Explanation:
-sS : makes curl run silent - not show request processing, etc., but still properly show errors
-H : adds HTTP headers needed to communicate with Unimus API
-d : data needed for various requests - not always needed
We will then pass the output to json_pp which will format the JSON received from the Unimus API.
The above curl command is the same as if written on one line (without the use of json_pp here):
curl -sS -H 'Authorization: Bearer <token>' -d '<data>' 'http://<unimus-address>:8085/api/v2/<API-path>' | json_pp |
You will need to substitute the values inside <...> for your actual values:
<token> : change this for your Unimus API token
<unimus-address> : change this for the actual address of your Unimus server
<API-path> : change this for the API path you wish to call
These curl examples are just examples.
We highly recommend checking the full API documentation for more information and options for each API call.
This API call will return the current status of Unimus.
Full API documentation#Healthcheck
curl call:
curl -sS \ -H 'Authorization: Bearer <token>' \ 'http://<unimus-address>:8085/api/v2/health' | json_pp |
Output:
{ "data" : { "status" : "OK" } } |
We can see that everything is OK, no issues with the system.
This API call will create a device with address <address>.
Full API documentation#Devices-createnewdevice
We are not passing a device description, nor explicitelly setting a schedule (so the default one will be used).
curl call:
curl -sS \ -H 'Content-type: application/json' \ -H 'Authorization: Bearer <token>' \ -d '{"address":"<address>"}' \ 'http://<unimus-address>:8085/api/v2/devices' | json_pp |
Output:
{ "vendor" : null, "port" : null, "connector" : null, "address" : "<address>", "description" : null, "model" : null, "type" : null, "createTime" : 1511974691, "credential" : null, "schedule" : { "createTime" : 1504105870, "hour" : 2, "dow" : 1, "id" : 2, "dom" : 1, "name" : "Every day at 02:00.", "min" : 0, "periodicity" : "DAILY" }, "id" : 92 } |
We can see the device was created with the default schedule, and is currently unknown.
Unimus will run a discovery on the device - since its a newly added device.
We need a valid deviceId to continue in the examples, so lets find the id of the device with address '1.1.1.1'.
Full API documentation#Devices-getdevicebyaddress
curl call:
curl -sS \ -H 'Authorization: Bearer <token>' \ 'http://<unimus-address>:8085/api/v2/devices/findByAddress/1.1.1.1' | json_pp |
Please note you might need to get multiple pages to find your device if you have many devices in Unimus.
To do this, simply change set the page to 2, 3, etc.
Output:
{ "data" : { "vendor" : "MikroTik", "connector" : "SSH", "address" : "198.18.0.1", "id" : 57, "schedule" : null, "model" : "Simulated-RouterOS", "credential" : null, "description" : null, "type" : "RouterOS", "createTime" : 1504195747, "port" : 22 } } |
Here we see the id of our device is 57.
We want to run a backup on a device - we know its id, so we can call the API.
Full API documentation#Runjob-backupdevice
curl call:
curl -sS \ -H 'Authorization: Bearer <token>' \ -X PATCH \ 'http://<unimus-address>:8085/api/v2/jobs/backup?id=57' | json_pp |
Output:
{ "data" : { "undiscovered" : 0, "refused" : 0, "accepted" : 1 } } |
Unimus is now performing the backup on the selected device.
We now want to retrieve the latest backup of our device.
Full API documentation#Backups-getdevicelatestbackup
curl call:
curl -sS \ -H 'Authorization: Bearer <token>' \ 'http://<unimus-address>:8085/api/v2/devices/57/backups/latest' | json_pp |
Output:
{ "data" : { "type" : "TEXT", "id" : 348, "bytes" : "IyBTaW11bGF0ZWQgTWlrcm9UaWsgUm91dGVyT1Mgc3lzdGVtCiMgc29mdHdhcmUgaWQgPSBub25lCiMKL3NlY3Rpb24gYQpjb21tYW5kIGEKL3NlY3Rpb24gYmIKY29tbWFuZCBiYgovc2VjdGlvbiBjY2MKY29tbWFuZCBjY2MK", "createTime" : 1511980661 } } |
We receive the backup as a byte array (UTF-8 encoded).