REST API examples

Warning: The Unomaly REST API is deprecated. It will still be available in releases until we announce a removal date. Please contact support if you're using the current API integration and have feedback on future functionality.

The Unomaly REST API allows you to query Unomaly for insights from within your own applications, to fetch the data into external systems and dashboards. The API exposes various parts of the user interface, such as Situations and Settings. The Unomaly REST API follows the RESTful standard.

  • The use the Unomaly API, you will need to authenticate using a token. This token can be found it Unomaly Settings > Authentication > API Access. In the "API Access" configuration, the API Token is the "Password".
  • Depending on your terminal program, the query parameters in these examples may need to be URL encoded before they are sent to the API. For instance, {"alert":1} needs to be %7B%22alert%22%3A1%7D . You can use online tools such as to encode the queries.

List and close alerts

You can use the Unomaly REST API to list the current open alerts and close them.

1. Show situations which have triggered alerts. These are the current open alerts:

$ curl -k -u api:exampletoken 'https://[unomaly]/restapi/situations?query="{alert:1}"&

From this you can get the unique ID, _id, and closing timestamp parameters for each alert.

2. Close the specified alert:

$ curl -k -u api:exampletoken -i -X POST -H "Content-Type:application/json" 
"https://[unomaly]/restapi/situations/5652c907b81f9e78cc569e8c" -d

List all defined knowns

A list of all defined knowns in Unomaly can be exported to integrate the knowledgebase with external systems.

$ curl -k -u api:exampletoken "https://[unomaly]/restapi/knowns?limit=1"

The above query will yield a JSON response with the following parameters:

"_id":"internal id",
"original_log":"log as it appears when known was created",
"name":"name of the known",
"classification":"the known classification",
"meaning":"the meaning entered when creating the known",
"count":numeric count of matches,
"original_parts":[identified parts of the original log],
"date_updated":"timestamp when known was updated",
"date_created":"timestamp when known was created",
"tags":[list of added tags],
"metalog_candidates":[list of internal pointers],
"anchors":[list of selected anchors],

Create system groups

The API supports data manipulation as well. This example shows how to create a group called “webservers”.

curl -i -k -u api:exampletoken -H "Content-Type:application/json" -X POST -d 
'{"name":"webservers","displayName":"webservers"}' https://[unomaly]/restapi/groups

The API will respond with the following information, and note the generated ID field.

HTTP/1.1 200 OK
Date: Wed, 11 Jan 2017 12:36:50 GMT
X-Powered-By: Express
Vary: X-HTTP-Method-Override
Content-Type: application/json; charset=utf-8
Content-Length: 32
ETag: W/"20-GOzV1CkWk/CimS5m7kFfAA"


Using the API makes it possible to easily integrate the group creation process to a third party system and use an API broker to automatically create the groups within Unomaly.

To add systems to the group, we first need to find the id for the system to add. To list all systems with their names and aliases, do:

curl -i -k -u api:exampletoken -H "Content-Type:application/json" 

The API will respond with a JSON of all systems and their ids, names and aliases. To then add a system to a group, use this query:

curl -i -k -u api:exampletoken -H "Content-Type:application/json" -X POST -d 
'{"group_id":50,"system_id":829}' https://[unomaly]/restapi/groupssystems

The API will respond with:

HTTP/1.1 200 OK
Date: Wed, 11 Jan 2017 12:46:45 GMT
X-Powered-By: Express
Vary: X-HTTP-Method-Override
Content-Type: application/json; charset=utf-8
Content-Length: 33
ETag: W/"21-83FnQTilRn2tAPTps3V03w"


Get status of instances

You can get the status of all Unomaly instances using the API and requesting /restapi/health.

$ curl -k -u api:exampletoken "https://[unomaly]/restapi/health

The API request returns JSON which includes a top-level status field. The status field checks that all services, including workers, are running normally.

  • If all instances report “OK”, the top level status will also be “OK”.
  • If status is not “OK” in one of the services, it will report “WARNING”.
"status": "OK",
"services": [
"_id": "59a013e83e24bd841e904522",
"ip": "",
"updated": 1510748837,
"version": " build: ec5c21a0eac1b3cbfe08577459da151de3c170e1",
"role": "standalone",
"port": "27017",
"retention" : {
"collections" : {
"messages" : {
"count" : 17323130,
"days" : 15.920518940988877,
"size" : 19027.33203125
"logs" : {
"count" : 109646,
"days" : 1.0816267816640206,
"size" : 2763.08203125
"anomalies" : {
"count" : 36549006,
"days" : 248228.82343182058,
"size" : 31391.74591064453
"type" : "database_stats"
"health": {
"status": "OK",
"services": {
"queuesplit": "RUNNING",
"situationd": "RUNNING",
"check": "RUNNING",
"mariadb": "RUNNING",
"systemstated": "RUNNING",
"celery-worker": "RUNNING",
"connect": "RUNNING",
"celery-beat": "RUNNING",
"api": "RUNNING",
"sinkd": "RUNNING",
"transportd": "RUNNING",
"unomalyweb": "RUNNING",
"nats": "RUNNING",
"tokeraggregated": "RUNNING",
"fluentd": "RUNNING",
"sith": "RUNNING"