APIv3

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/

APIv2

For APIv2 curl examples, please see below.

Format of curl examples

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.

Examples

Get current status of your Unimus server

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.

Add a device into Unimus

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.

Find device id by device address

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.

Run a backup on a device

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.

Retrieve latest backup of a 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).