Unomaly API (2.0.0)

Introduction

Welcome to the Unomaly REST API Reference!

This is the reference manual for interacting with the Unomaly REST API. For more information, see the Unomaly product Documentation. You may want to start with the core concepts of Unomaly.

Accessing the API

To generate credentials to access the API, you need to configure at least one Basic authentication in Settings > Authentication. See documentation.

Use the username and password of the authentication to create an authentication header base64(username + ":" + password)

Send API requests to your running instance of Unomaly at https://{your-unomaly-instance}/api/v2/.

Request example

Sending a request to get a list of groups using username api and password password.

  GET https://{your-unomaly-instance}/api/v2/groups HTTP/1.1
  Authorization: Basic YXBpOnBhc3N3b3Jk

Expected response with two groups:

  {
    items: [{
      id: "3",
      name: "group-a",
      created: "2019-10-01T08:32:36.649Z",
      updated: "2019-10-01T08:32:36.649Z",
    },
    {
      id: "4",
      name: "group-b",
      created: "2019-10-05T11:13:56.262Z",
      updated: "2019-10-07T09:53:23.853Z",
    }],
    total: 2
  }

Pagination and cursors

Most responses for lists of entities are paginated by default. You can usually supply a limit query parameter to control how many results are being returned. In the result, there may be a next and/or prev cursor being returned. You can use these to get the next or previous set of items in the list. The cursors are only valid as long as the sorting field and order are unchanged. You can change the limit to vary the number of elements returned. A response returning next or prev cursors doesn't not guarantee there are more results to be returned.

Getting the first group:

  GET https://{your-unomaly-instance}/api/v2/groups?limit=1 HTTP/1.1
  Authorization: Basic YXBpOnBhc3N3b3Jk

Expected response:

  {
    items: [{
      id: "3",
      name: "group-a",
      created: "2019-10-01T08:32:36.649Z",
      updated: "2019-10-01T08:32:36.649Z",
    }],
    total: 2,
    next: "WzE2NSwiYm9vMiJd",
    prev: "WzE2NiwiYm9vMngiXQ",
  }

You can now use the next cursor to get the next set of results.

  GET https://{your-unomaly-instance}/api/v2/groups?limit=1&next=WzE2NSwiYm9vMiJd HTTP/1.1
  Authorization: Basic YXBpOnBhc3N3b3Jk

Expected response:

  {
    items: [{
      id: "4",
      name: "group-b",
      created: "2019-10-05T11:13:56.262Z",
      updated: "2019-10-07T09:53:23.853Z",
    }],
    total: 2,
    next: "WzE2NiwiYm9vMngiXQ",
    prev: "WzE2NiwiYm9vMngiXQ",
  }

List groups

List groups.

query Parameters
limit
number >= 1
Default: 20

limit the number of results returned

order
string
Default: "ASC"
Enum: "ASC" "DESC"
next
string

Opaque cursor for next set of results

prev
string

Opaque cursor for previous set of results

sortBy
string
Default: "name"

Column to sort by

Responses

200

A list of groups

500

An unexpected error occured.

get /groups
/api/v2/groups

Response samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "items":
    [
    • {
      }
    ],
  • "next": "WyJhbm90aGVyIHZhbHVlIl0",
  • "total": 5
}

Create a new group

Create a new group

Request Body schema: application/json; charset=utf-8

Group name has to be unique

name
required
string
parentId
string

ID of group

Responses

200

Group has been creted successfully

400

Bad request.

403

Access forbidden

409

Name conflict

500

An unexpected error occured.

post /groups
/api/v2/groups

Request samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "name": "Webservers",
  • "parentId": "string"
}

Response samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "MyGroupName",
  • "parentId": null,
  • "created": "2019-12-02T12:16:07Z",
  • "updated": "2019-12-02T12:16:07Z"
}

Get group by ID

Get group by ID

path Parameters
groupID
required
string
Example: 1

ID of group

Responses

200

Group by ID

403

Access forbidden

404

Resource has not been found.

get /groups/{groupID}
/api/v2/groups/{groupID}

Response samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "MyGroupName",
  • "parentId": null,
  • "created": "2019-12-02T12:16:07Z",
  • "updated": "2019-12-02T12:16:07Z"
}

Update group

path Parameters
groupID
required
string
Example: 1

ID of group

Request Body schema: application/json; charset=utf-8

partial group object to update

name
required
string^[a-zA-Z0-9\-_]+$
parentId
string Nullable

Responses

200

Updated group

403

Access forbidden

404

Resource has not been found.

409

Name conflict

500

An unexpected error occured.

patch /groups/{groupID}
/api/v2/groups/{groupID}

Request samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "name": "MyGroupName",
  • "parentId": null
}

Response samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "id": "string",
  • "name": "MyGroupName",
  • "parentId": null,
  • "created": "2019-12-02T12:16:07Z",
  • "updated": "2019-12-02T12:16:07Z"
}

Delete group

Delete a group

path Parameters
groupID
required
string
Example: 1

ID of group

Responses

200

Response after deleting an entity.

403

Access forbidden

404

Resource has not been found.

500

An unexpected error occured.

delete /groups/{groupID}
/api/v2/groups/{groupID}

Response samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "message": "Item was deleted"
}

Get systems of a group

path Parameters
groupID
required
string
Example: 1

ID of group

query Parameters
limit
number >= 1
Default: 20

limit the number of results returned

order
string
Default: "ASC"
Enum: "ASC" "DESC"
next
string

Opaque cursor for next set of results

prev
string

Opaque cursor for previous set of results

sortBy
string
Default: "name"

Column to sort by

Responses

200

A list of all systems belong to a group

500

An unexpected error occured.

get /groups/{groupID}/systems
/api/v2/groups/{groupID}/systems

Response samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "items":
    [
    • {
      }
    ],
  • "total": 1
}

Add system(s) to a group

Add system(s) to a group

path Parameters
groupID
required
string
Example: 1

ID of group

Request Body schema: application/json; charset=utf-8

List of system ids

Array
number

Responses

200

Updated group

404

Resource has not been found.

500

An unexpected error occured.

post /groups/{groupID}/systems
/api/v2/groups/{groupID}/systems

Request samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
[
  • 23,
  • 24,
  • 34
]

Response samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "message": "Added 2 systems to group"
}

Remove system(s) from a group

Remove system(s) from a group

path Parameters
groupID
required
string
Example: 1

ID of group

Request Body schema: application/json; charset=utf-8

List of system ids

Array
string

Responses

200

Updated group

404

Resource has not been found.

500

An unexpected error occured.

delete /groups/{groupID}/systems
/api/v2/groups/{groupID}/systems

Request samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
[
  • "23",
  • "24",
  • "34"
]

Response samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "message": "Removed 2 systems from group"
}

Get systems of a group

path Parameters
groupID
required
string
Example: 1

ID of group

query Parameters
limit
number >= 1
Default: 20

limit the number of results returned

order
string
Default: "ASC"
Enum: "ASC" "DESC"
next
string

Opaque cursor for next set of results

prev
string

Opaque cursor for previous set of results

sortBy
string
Default: "name"

Column to sort by

Responses

200

A list of all systems belong to a group

500

An unexpected error occured.

get /groups/{groupID}/systems
/api/v2/groups/{groupID}/systems

Response samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "items":
    [
    • {
      }
    ],
  • "total": 1
}

Add system(s) to a group

Add system(s) to a group

path Parameters
groupID
required
string
Example: 1

ID of group

Request Body schema: application/json; charset=utf-8

List of system ids

Array
number

Responses

200

Updated group

404

Resource has not been found.

500

An unexpected error occured.

post /groups/{groupID}/systems
/api/v2/groups/{groupID}/systems

Request samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
[
  • 23,
  • 24,
  • 34
]

Response samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "message": "Added 2 systems to group"
}

Remove system(s) from a group

Remove system(s) from a group

path Parameters
groupID
required
string
Example: 1

ID of group

Request Body schema: application/json; charset=utf-8

List of system ids

Array
string

Responses

200

Updated group

404

Resource has not been found.

500

An unexpected error occured.

delete /groups/{groupID}/systems
/api/v2/groups/{groupID}/systems

Request samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
[
  • "23",
  • "24",
  • "34"
]

Response samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "message": "Removed 2 systems from group"
}

List systems

query Parameters
limit
number >= 1
Default: 20

limit the number of results returned

order
string
Default: "ASC"
Enum: "ASC" "DESC"
next
string

Opaque cursor for next set of results

prev
string

Opaque cursor for previous set of results

sortBy
string
Default: "name"

Column to sort by

Responses

200

A list of all systems

500

An unexpected error occured.

get /systems
/api/v2/systems

Response samples

Content type
application/json; charset=utf-8
Copy
Expand all Collapse all
{
  • "items":
    [
    • {
      }
    ],
  • "total": 25,
  • "next": "WyJhbm90aGVyIHZhbHVlIl0"
}

Delete multiple systems

Removes a list of systems specified in the request.

Request Body schema: application/json; charset=utf-8

List of system ids

Array
string

Responses

200

Response after deleting an entity.

403

Access forbidden

404

Resource has not been found.

500

An unexpected error occured.

delete /systems
/api/v2/systems

Request samples

Content type
application/json; charset=utf-8