API Reference



Welcome to the Enginsight API documentation!


As our platform is growing in functionality, performance and possibilities day by day, it is important to us that you can access the API easy and comfortable. That is why we explain all the possibilities our API offers in the current version 1.26.70. You can access the API with the following URL: https://api.enginsight.com

If you got any questions about API calls that are not documented yet, feel free to contact our support at support@enginsight.com.

Do you want to build your own apps upon our API? Feel free to check out our swagger file for more details.

API Endpoint
https://app.enginsight.com/
Contact: support@enginsight.com
Schemes: https, http
Version: 1.26.70

Authentication

Access Key Id

The authentication process is handled via apiKeys. You will need the access key id as well as the access key secret. If you don't know where to find them, don't worry. You can create your keys with just some clicks using the Enginsight platform as follows:

1.    Log in to your Enginsight account.
swagger2.json    Go to 'Einstellungen'.
3.    Press 'Access Key Erstellen' in the top right corner.
4.    Fill in the description and decide for a service.

The access key id will be shown right away.

type
apiKey
name
x-ngs-access-key-id
in
header

Access Key Secret

To make the access key secret visible just press 'Secrets Ein-/ Ausblenden' in the top right corner.

type
apiKey
name
x-ngs-access-key-secret
in
header

Users

As you read the api documentation you are probably a user. Areas in Enginsight are shared by users of an organisation. In that way it is easy to work together with other users of your organisation. The following operations describe how you can use our api to update/delete/create users or how to get information about users.

Current user

GET /v1/users/me/

Shows information of the user that is currently logged in.

200 OK

Successful operation

404 Not Found

User not found

Response Example (200 OK)
{
  "name": "Doe",
  "firstName": "Jon",
  "email": "mail@jondoe.com",
  "phone": "004912345678999",
  "language": "en"
}

Update user

PUT /v1/users/{id}

Updates the information of the belonging to the given id.

Updated information of the user.

id: string
in path

ID of user.

Request Example
{
  "name": "Doe",
  "firstName": "Jon",
  "email": "mail@jondoe.com",
  "phone": "004912345678999",
  "language": "en"
}
200 OK

Successful operation

404 Not Found

User not found

Log in user

POST /v1/users/login/

To be able to work with our api, a user must verified. That is done via log in process.

email: string
in query

Email of user.

password: string
in query

Password of user.

permanent: boolean
in query

If true, user stays logged in for a week.

200 OK

Successful operation

404 Not Found

User not found

Response Example (200 OK)
{
  "name": "Doe",
  "firstName": "Jon",
  "email": "mail@jondoe.com",
  "phone": "004912345678999",
  "language": "en"
}

Hosts

We define hosts as physical and virtual servers, PCs, as well as IoT-Devices. Pretty much any device that the Enginsight Client can be installed on. The following operations describe how you can use our api to interact with your hosts.

List hosts

GET /v1/hosts/

Returns a list of accessable hosts.

200 OK

Successful operation

404 Not Found

Host not found

Response Example (200 OK)
[
  {
    "hostname": "Laptop-HP123-456XYZ",
    "alias": "OfficeBerlin_Laptop_HP",
    "description": "My secured host.",
    "tags": [
      "host"
    ],
    "os": {
      "name": "windows",
      "platform": "Microsoft Windows 10 Home",
      "platformFamily": "Standalone Workstation",
      "platformVersion": "1.2.3 Build 123",
      "uptime": 5,
      "kernelVersion": ""
    },
    "nics": {
      "flags": [
        "broadcast"
      ],
      "addresses": [
        "1.2.3.4/5"
      ],
      "mtu": 5,
      "name": "Interface",
      "mac": "0:a:0:b:0:c",
      "guid": ""
    },
    "ram": 500,
    "swap": 50
  }
]

Add host

POST /v1/hosts/

Adds a host to the list of observed hosts.

Information of the new host.

Request Example
{
  "hostname": "Laptop-HP123-456XYZ",
  "alias": "OfficeBerlin_Laptop_HP",
  "description": "My secured host.",
  "tags": [
    "host"
  ],
  "os": {
    "name": "windows",
    "platform": "Microsoft Windows 10 Home",
    "platformFamily": "Standalone Workstation",
    "platformVersion": "1.2.3 Build 123",
    "uptime": 5,
    "kernelVersion": ""
  },
  "nics": {
    "flags": [
      "broadcast"
    ],
    "addresses": [
      "1.2.3.4/5"
    ],
    "mtu": 5,
    "name": "Interface",
    "mac": "0:a:0:b:0:c",
    "guid": ""
  },
  "ram": 500,
  "swap": 50
}
200 OK

Successfully created a new host

404 Not Found

Host not found

Get host

GET /v1/hosts/{id}

Returns all information to the specific host from the system that the user has access to.

id: string
in path

ID of wanted host.

200 OK

Successful operation

404 Not Found

Host not found

Response Example (200 OK)
{
  "hostname": "Laptop-HP123-456XYZ",
  "alias": "OfficeBerlin_Laptop_HP",
  "description": "My secured host.",
  "tags": [
    "host"
  ],
  "os": {
    "name": "windows",
    "platform": "Microsoft Windows 10 Home",
    "platformFamily": "Standalone Workstation",
    "platformVersion": "1.2.3 Build 123",
    "uptime": 5,
    "kernelVersion": ""
  },
  "nics": {
    "flags": [
      "broadcast"
    ],
    "addresses": [
      "1.2.3.4/5"
    ],
    "mtu": 5,
    "name": "Interface",
    "mac": "0:a:0:b:0:c",
    "guid": ""
  },
  "ram": 500,
  "swap": 50
}

Update host

PUT /v1/hosts/{id}

Updates information of a specific host.

Updated information of the host.

id: string
in path

The host ID

Request Example
{
  "hostname": "Laptop-HP123-456XYZ",
  "alias": "OfficeBerlin_Laptop_HP",
  "description": "My secured host.",
  "tags": [
    "host"
  ],
  "os": {
    "name": "windows",
    "platform": "Microsoft Windows 10 Home",
    "platformFamily": "Standalone Workstation",
    "platformVersion": "1.2.3 Build 123",
    "uptime": 5,
    "kernelVersion": ""
  },
  "nics": {
    "flags": [
      "broadcast"
    ],
    "addresses": [
      "1.2.3.4/5"
    ],
    "mtu": 5,
    "name": "Interface",
    "mac": "0:a:0:b:0:c",
    "guid": ""
  },
  "ram": 500,
  "swap": 50
}
200 OK

Successful operation

404 Not Found

Host not found

Delete host

DELETE /v1/hosts/{id}

Deletes a specific host.

id: string
in path

The host ID

200 OK

Successful operation

404 Not Found

Host not found

Get Report

GET /v1/hosts/{id}/reports/latest

Gets the most current report of the host identified by id.

id: string
in path

The host ID

200 OK

Successful operation

404 Not Found

Host not found

Endpoints

As an endpoint we define instances of the following types: domains, url's, hostnames, websites and ip-addresses that are reachable by a network (for example the internet).

Create endpoint

POST /v1/endpoints/

Creates an endpoint for the current organisation

Information of the new endpoint

Request Example
{
  "target": "https://example.com",
  "description": "My secured website.",
  "tags": [
    "endpoint"
  ],
  "observe": {
    "website": {
      "enabled": "true"
    },
    "sslTls": {
      "enabled": "true"
    },
    "httpHeaders": {
      "enabled": "true"
    },
    "wti": {
      "enabled": "true"
    },
    "portScan": {
      "enabled": "true"
    },
    "meta": {
      "enabled": "true"
    }
  },
  "regions": [
    "eu-central-frankfurt"
  ]
}
200 OK

Successful created an the endpoint

404 Not Found

Endpoint could not be created.

Get endpoint

GET /v1/endpoints/{id}

Return the endpoint with its data, specified by id.

id: string
in path

ID of wanted endpoint.

200 OK

Successful operation.

404 Not Found

Endpoint could not be found.

Response Example (200 OK)
{
  "target": "https://example.com",
  "description": "My secured website.",
  "tags": [
    "endpoint"
  ],
  "observe": {
    "website": {
      "enabled": "true"
    },
    "sslTls": {
      "enabled": "true"
    },
    "httpHeaders": {
      "enabled": "true"
    },
    "wti": {
      "enabled": "true"
    },
    "portScan": {
      "enabled": "true"
    },
    "meta": {
      "enabled": "true"
    }
  },
  "regions": [
    "eu-central-frankfurt"
  ]
}

Update endpoint

PUT /v1/endpoints/{id}

Updates the endpoint specified by id.

Information of the updated endpoint

id: string
in path

ID of wanted endpoint.

Request Example
{
  "target": "https://example.com",
  "description": "My secured website.",
  "tags": [
    "endpoint"
  ],
  "observe": {
    "website": {
      "enabled": "true"
    },
    "sslTls": {
      "enabled": "true"
    },
    "httpHeaders": {
      "enabled": "true"
    },
    "wti": {
      "enabled": "true"
    },
    "portScan": {
      "enabled": "true"
    },
    "meta": {
      "enabled": "true"
    }
  },
  "regions": [
    "eu-central-frankfurt"
  ]
}
200 OK

Successful operation.

404 Not Found

Endpoint could not be found.

Delete endpoint

DELETE /v1/endpoints/{id}

Deletes the endpoint specified by id.

id: string
in path

ID of wanted endpoint.

200 OK

Successful operation.

404 Not Found

Endpoint could not be found.

Alerts

Alerts are scenarios you can define as you need them. If those scenarios occure an issue is created. With those alerts it is easy to keep an eye on your IT landscape without any great effort. It is also possible to trigger certain events (plugins), when an alert occurs or even when it is resolved.

Issues

Issues describe triggered alerts. As long as a scenario occurs, that you have declared within your alerts, issues provide an overview over any problems in you IT landscape. For a certain time, issues are also stored after they are resolved.

Get issues

GET /v1/issues/

Lists all issues of the users organisation.

200 OK

Successful operation.

404 Not Found

No issues found.

Response Example (200 OK)
[
  {
    "resolved": true,
    "reference": "ObjectId('ABC123DEF456GHI789HIJKLM')",
    "belongsTo": "endpoint",
    "alert": "ObjectId('alertABC123DEF456GHI789H')",
    "payload": {
      "property": {
        "name": "website.total",
        "operator": "gt",
        "threshold": "0"
      },
      "result": {
        "value": "5"
      },
      "category": "ObjectId('alertABC123DEF456GHI789H')"
    }
  }
]

Organisations

An organisation consists out of members or as we call them users. Any alerts, issues, endpoints, hosts as well as plugins and much more is organized in organisations. That makes it possible, that you as an individual user can keep track about everything what is going on in your entire IT landscape.

Get members

GET /v1/organisations/members

Return all members of the current organisation

200 OK

Successful operation

404 Not Found

User not found

Response Example (200 OK)
[
  {
    "name": "Doe",
    "firstName": "Jon",
    "email": "mail@jondoe.com",
    "phone": "004912345678999",
    "language": "en"
  }
]

Show organisation

GET /v1/users/me/organisations

Shows organisations of the user that is currently logged in.

200 OK

Successful operation

404 Not Found

Organisation not found

Response Example (200 OK)
{
  "name": "Example Cooperation",
  "email": "mail@example.com",
  "adress": {
    "street": "Main Street 1",
    "city": "Luckenwalde",
    "zipCode": "12345",
    "country": "Germany"
  }
}

Miscellaneous

While improving our functionality, some api calls do not only belong to one component. For example invoices work with data from different sources. So this section will include any api calls referring to different components of the Enginsight platform.

Get invoices

GET /v1/miscs/invoices/

Returns a list of all invoices of the current organisation.

200 OK

Successful operation

404 Not Found

No invoice found

Response Example (200 OK)
[
  {
    "paid": true,
    "closed": true,
    "pricing": 555,
    "paidFor": "2019-06-24T05:05:00.000Z",
    "createdAt": "2018-06-24T05:05:00.000Z",
    "invoicePath": "Example_Cooperation_ABC123-0005.pdf"
  }
]

Get current invoice

GET /v1/miscs/invoices/latest

Returns the most current invoice of the current organisation.

200 OK

Successful operation

404 Not Found

Invoice not found

Response Example (200 OK)
{
  "paid": true,
  "closed": true,
  "pricing": 555,
  "paidFor": "2019-06-24T05:05:00.000Z",
  "createdAt": "2018-06-24T05:05:00.000Z",
  "invoicePath": "Example_Cooperation_ABC123-0005.pdf"
}

Get specific invoice

GET /v1/miscs/invoices/{invoicePath}

Returns the invoice belonging to the invoicePath.

invoicePath: string
in path

The invoice path.

200 OK

Successful operation

404 Not Found

Invoice not found

Response Example (200 OK)
{
  "paid": true,
  "closed": true,
  "pricing": 555,
  "paidFor": "2019-06-24T05:05:00.000Z",
  "createdAt": "2018-06-24T05:05:00.000Z",
  "invoicePath": "Example_Cooperation_ABC123-0005.pdf"
}

Schema Definitions

User: object

name: string
firstName: string
email: string
phone: string
language: string de, en
Example
{
  "name": "Doe",
  "firstName": "Jon",
  "email": "mail@jondoe.com",
  "phone": "004912345678999",
  "language": "en"
}

Host: object

hostname: string
alias: string

Alternative hostname to display

description: string

Description of the host entered by the user.

tags: string[]

Tags are used by Enginsight to create groups of endpoints and hosts to declare operations on these groups instead of a single asset.

string
os: object
name: string

Name of operation system (linux, windows, etc.)

platform: string
platformFamily: string
platformVersion: string
uptime: integer

Amount of seconds that the host is up and running.

kernelVersion: string

Kernel version if Linux platform.

nics: object
flags: string[]
string
addresses: string[]
string
mtu: integer
name: string
mac: string
guid: string
ram: integer

MB Capacity of RAM on the host.

swap: integer

MB Capacity of SWAP on the host.

Example
{
  "hostname": "Laptop-HP123-456XYZ",
  "alias": "OfficeBerlin_Laptop_HP",
  "description": "My secured host.",
  "tags": [
    "host"
  ],
  "os": {
    "name": "windows",
    "platform": "Microsoft Windows 10 Home",
    "platformFamily": "Standalone Workstation",
    "platformVersion": "1.2.3 Build 123",
    "uptime": 5,
    "kernelVersion": ""
  },
  "nics": {
    "flags": [
      "broadcast"
    ],
    "addresses": [
      "1.2.3.4/5"
    ],
    "mtu": 5,
    "name": "Interface",
    "mac": "0:a:0:b:0:c",
    "guid": ""
  },
  "ram": 500,
  "swap": 50
}

Endpoint: object

target: string

URL of the observed endpoint.

description: string

Describe your endpoint.

tags: string[]

Tags are used by Enginsight to create groups of endpoints and hosts to declare operations on these groups instead of a single asset.

string
observe: object
website: object
enabled: boolean
sslTls: object
enabled: boolean
httpHeaders: object
enabled: boolean
wti: object
enabled: boolean
portScan: object
enabled: boolean
meta: object

If enabled, takes description of website from meta data if the description was not set manually.

enabled: boolean
regions: string[]

Declares the location of the observing servers. Currently available: 'eu-central-frankfurt' and 'us-east-virginia'

string eu-central-frankfurt, us-east-virginia
Example
{
  "target": "https://example.com",
  "description": "My secured website.",
  "tags": [
    "endpoint"
  ],
  "observe": {
    "website": {
      "enabled": "true"
    },
    "sslTls": {
      "enabled": "true"
    },
    "httpHeaders": {
      "enabled": "true"
    },
    "wti": {
      "enabled": "true"
    },
    "portScan": {
      "enabled": "true"
    },
    "meta": {
      "enabled": "true"
    }
  },
  "regions": [
    "eu-central-frankfurt"
  ]
}

Alert: object

description: string

Chosen by the user to describe the alert.

reference: string

ObjectId of the host or endpoint.

belongsTo: string

Type of asset ("endpoint" or "host")

plugins: object[]

Plugins describe processes that are triggered automatically if an alert is triggered or resolved.

object
enabled: boolean

Indicates whether the alert triggers an plugin or not.

plugin: string

ID of the triggered plugin.

configuration: object[]
object
gate: string
logic: object[]
object

Indicates the condition for the alert not to be triggered.

scenario: object
name: string

Indicates what exactly gets observed.

negate: boolean

If true, the alert is triggered exactly when the condition is met.

operator: string gt, lt, gte, lte, eq, neq

Indicator for the condition.

threshold: string

Indicates threshold that needs to be exceeded for an alert to be triggered.

Example
{
  "description": "Website down.",
  "reference": "ObjectId('ABC123DEF456GHI789HIJKLM')",
  "belongsTo": "endpoint",
  "plugins": [
    {
      "enabled": "true",
      "plugin": "plugin123abc456def789ghi"
    }
  ],
  "configuration": [
    {
      "gate": "and",
      "logic": [
        {
          "scenario": {
            "name": "endpoint_dataProtection",
            "negate": "false",
            "operator": "gt",
            "threshold": "5"
          }
        }
      ]
    }
  ]
}

Issue: object

resolved: boolean

If issue is resolved, set to false.

reference: string

ObjectId of the host or endpoint.

belongsTo: string

Type of asset ("endpoint" or "host")

alert: string

ObjectId of the alert that triggered the issue.

payload: object

Payload with the information why the issue was triggered. For example an exceedance of a given threshold.

property: object
name: string
operator: string
threshold: string
result: object
value: string
category: string

ObjectId of the alert that triggered the issue.

Example
{
  "resolved": true,
  "reference": "ObjectId('ABC123DEF456GHI789HIJKLM')",
  "belongsTo": "endpoint",
  "alert": "ObjectId('alertABC123DEF456GHI789H')",
  "payload": {
    "property": {
      "name": "website.total",
      "operator": "gt",
      "threshold": "0"
    },
    "result": {
      "value": "5"
    },
    "category": "ObjectId('alertABC123DEF456GHI789H')"
  }
}

Organisation: object

name: string
email: string

Email of the main user.

adress: object
street: string
city: string
zipCode: string
country: string
Example
{
  "name": "Example Cooperation",
  "email": "mail@example.com",
  "adress": {
    "street": "Main Street 1",
    "city": "Luckenwalde",
    "zipCode": "12345",
    "country": "Germany"
  }
}

Invoice: object

paid: boolean

Indicates if this invoice was paid already.

closed: boolean

Indicates if this invoice is canceled.

pricing: integer

Indicates if cent amount (Eurocent) of the invoice.

paidFor: string (date-time)

Indicates the date until which the customer paid for.

createdAt: string (date-time)

Indicates the date on which the invoice was created.

invoicePath: string

Indicates filename of the corresponding PDF.

Example
{
  "paid": true,
  "closed": true,
  "pricing": 555,
  "paidFor": "2019-06-24T05:05:00.000Z",
  "createdAt": "2018-06-24T05:05:00.000Z",
  "invoicePath": "Example_Cooperation_ABC123-0005.pdf"
}

Hosts: array

Array of hosts.

Host
Example
[
  {
    "hostname": "Laptop-HP123-456XYZ",
    "alias": "OfficeBerlin_Laptop_HP",
    "description": "My secured host.",
    "tags": [
      "host"
    ],
    "os": {
      "name": "windows",
      "platform": "Microsoft Windows 10 Home",
      "platformFamily": "Standalone Workstation",
      "platformVersion": "1.2.3 Build 123",
      "uptime": 5,
      "kernelVersion": ""
    },
    "nics": {
      "flags": [
        "broadcast"
      ],
      "addresses": [
        "1.2.3.4/5"
      ],
      "mtu": 5,
      "name": "Interface",
      "mac": "0:a:0:b:0:c",
      "guid": ""
    },
    "ram": 500,
    "swap": 50
  }
]

Invoices: array

Array of invoices.

Invoice
Example
[
  {
    "paid": true,
    "closed": true,
    "pricing": 555,
    "paidFor": "2019-06-24T05:05:00.000Z",
    "createdAt": "2018-06-24T05:05:00.000Z",
    "invoicePath": "Example_Cooperation_ABC123-0005.pdf"
  }
]

Users: array

Array of users.

User
Example
[
  {
    "name": "Doe",
    "firstName": "Jon",
    "email": "mail@jondoe.com",
    "phone": "004912345678999",
    "language": "en"
  }
]

Issues: array

Array of issues.

Issue
Example
[
  {
    "resolved": true,
    "reference": "ObjectId('ABC123DEF456GHI789HIJKLM')",
    "belongsTo": "endpoint",
    "alert": "ObjectId('alertABC123DEF456GHI789H')",
    "payload": {
      "property": {
        "name": "website.total",
        "operator": "gt",
        "threshold": "0"
      },
      "result": {
        "value": "5"
      },
      "category": "ObjectId('alertABC123DEF456GHI789H')"
    }
  }
]