WEDOS EWM – API Documentation

WEDOS Early Warning and Monitoring (EWM) offers API, an application program interface to help users find out information about their account, service checks and their current status. They can connect our monitoring system to their application or automatically monitor new events for monitored domains and services.

API Activation

Access to the API can be activated in the EWM administration, which you can access via the client.wedos.com page in the details of the specific domain for which you have activated this additional service. In the EWM administration, choose the Settings -> API Settings section. Activation will generate an API key (similar to a password), which you will then use for authentication in API communication.

Basic Information

Communication with the API interface takes place using HTTPS, the GET method is used. Some methods accept parameters in the URL (GET parameters).

All methods return a response in the form of a JSON object. All data in the response is in UTF-8 encoding.

Each response has a requestId entry that uniquely identifies the request. According to this identifier, we are able to find specific communication in our log in the event that a problem or question arises.

The API is located at https://api.wedos.online/mon/ + the name of the specific method.

User authentication is performed using special HTTP headers – each request includes the API key ID (X-Auth-Id) and API key (X-Auth-Key).

The API has the following limitations:

  • max. 1000 requests per hour from one IP address
  • max. 1000 requests per hour from one user

Hello World!

This is a basic call to a method called a ping, which simply checks that the connection and authentication works.

GET /mon/ping HTTP/1.1
Host: api.wedos.online
Accept: application/json
X-Auth-Id: MY_API_KEY_ID
X-Auth-Key: MY_API_KEY

And the response could look like this:

{
    "stamp": 1613393366,
    "time": "2021-02-15 13:49:26",
    "userId": 1000,
    "requestId": "3bb52d4d22.1613393366.2811.82063"
}

In case of an error, the HTTP server returns a response code other than 200 and there is an specification of the error in the body of the response – the error code and its description are given. Example:

{
    "error": {
        "code": "C507",
        "error": "Authentication failed"
    },
    "requestId": "1495544185.1615.8422"
}

Lists, Filtering, Paging

Some API methods return a list of some items (for example checks). These methods have common functions and common input parameters and output data.

The result always includes the following items:

  • results – array of objects with individual list items
  • page – page number (see paging below)
  • count – number of returned items
  • filteredCount – number of all items that correspond to the current filter (see filtering below)
  • totalCount – number of all items

Example response (specific items are not listed here):

{
    "results": [
        ...
    ],
    "page": 1,
    "count": 10,
    "filteredCount": 18,
    "totalCount": 624,
    "requestId": "..."
}

This particular response means that there are a total of 624 items in the database for the current user (eg. checks), of which 18 correspond to active filter(s) and the first 10 items were returned (first page, paging after 10 items).

One or more filters can be specified in the list request. These are referred to as GET parameters. The items that are selected are returned accordingly.

List items can be paged, ie returned only after certain numbers. The API allows a maximum of 1000 items per call. The default paging is 100 items.

The following input GET parameters can be used for paging and / or limiting the number of returned items:

  • page – page number (default 1)
  • count – number of returned items, ie page size (default 100)

Example of a listing of 10 items on the second page (ie items 11 to 20):

https://api.wedos.online/mon/checks?page=2&count=10

Checks List

A method called checks allow to fetch a list of monitored services in your account.

Request URL:

https://api.wedos.online/mon/checks

Response example:

{
    "results": [
        {
            "ID": 5151,
            "name": "seznam.cz DNSSEC",
            "type": "dnssec",
            "period": 600,
            "fullTarget": "seznam.cz",
            "status": "ok",
            "statusStamp": 1612886736,
            "statusDate": "2021-02-09 16:05:36",
            "createdStamp": 1612886708,
            "createdDate": "2021-02-09 16:05:08",
            "uptime_1d": 100,
            "errorSeconds_1d": 0,
            "avgTime_1d": 0,
            "uptime_7d": 100,
            "errorSeconds_7d": 0,
            "avgTime_7d": 0,
            "uptime_30d": 100,
            "errorSeconds_30d": 0,
            "avgTime_30d": 0,
            "warningsCount": 0
        },
        ...
    ],
    "page": 1,
    "count": 21,
    "filteredCount": 21,
    "totalCount": 21,
    "requestId": "3bb52d4d22.1613394688.5186.82182"
}

You can filter the list by status and/or type, for example:

https://api.wedos.online/mon/checks?type=http&status=down

The meaning of the items in the response:

  • ID – check ID
  • name – check name
  • type – check type (ping, http, dns, smtp, …)
  • period – test interval (seconds)
  • fullTarget – host/domain name of the target (domain name, server)
  • status – current check status (ok, slow, response_timeout, down, response_error, disabled, …)
  • statusStamp – last status change (UNIX timestamp)
  • statusDate – last status change (SQL format, UTC)
  • createdStamp – check creation date and time (UNIX timestamp)
  • createdDate – check creation date and time (SQL format, UTC)
  • uptime_1d – uptime in the last 24 hours (percent)
  • errorSeconds_1d – number of second in error state in the last 24 hours
  • avgTime_1d – average response time in the last 24 hours (seconds)
  • uptime_7d – uptime inthe last 7 days (percent)
  • errorSeconds_7d – number of second in error state in the last 7 days
  • avgTime_7d – average response time in the last 7 days (seconds)
  • uptime_30d – uptime inthe last 30 days (percent)
  • errorSeconds_30d – number of second in error state in the last 30 days
  • avgTime_30d – average response time in the last 30 days (seconds)
  • warningsCount – number of active warnings

The status can be:

  • unknown – test not performed yet
  • ok – everything is okay
  • slow – response was successful, but slow
  • response_timeout – connection was successful, but got timeout when waiting for a response
  • down – connection failed
  • response_error – invalid response
  • maintenance – check is in planned maintenance
  • paused – check is paused, no tests are performed
  • disabled – check was disabled by an administrator
  • denied – the monitoring system refused to perform the test, usually it means that you are trying to connect to an IP address that belongs to a private range
  • unverified – you did not verify the ownership of the website you want to monitor (applies to HTTP checks)
  • invalidStatus – other invalid status of monitored service

Check Detail

There is a check method that shows more details about one particular check (monitored service). You simply add an ID of the check to the URL adress, example:

https://api.wedos.online/mon/check/5151

Response example:

{
    "check": {
        "ID": 5151,
        "name": "seznam.cz DNSSEC",
        "type": "dnssec",
        "period": 600,
        "fullTarget": "seznam.cz",
        "status": "ok",
        "statusStamp": 1612886736,
        "statusDate": "2021-02-09 16:05:36",
        "createdStamp": 1612886708,
        "createdDate": "2021-02-09 16:05:08",
        "uptime_1d": 100,
        "errorSeconds_1d": 0,
        "avgTime_1d": 0,
        "uptime_7d": 100,
        "errorSeconds_7d": 0,
        "avgTime_7d": 0,
        "uptime_30d": 100,
        "errorSeconds_30d": 0,
        "avgTime_30d": 0,
        "warningsCount": 0,
        "lastTestStamp": 1613396132,
        "lastTestDate": "2021-02-15 13:35:32",
        "requestTime": null,
        "info": "seznam.cz/SOA secured by DNSSEC\nSignature expiration: 2021-02-28 16:01:01 UTC",
        "testsCount": 363,
        "errorsCount": 0,
        "pendingErrorsCount": 0,
        "lastErrorBeginStamp": null,
        "ip": null,
        "ptr": null,
        "nextStamp": 1613396731,
        "warnings": []
    },
    "requestId": "3bb52d4d22.1613396687.4247.82403"
}

There are some additional information about the check:

  • lastTestStamp – test last performed (UNIX timestamp)
  • lastTestDate – test last performed (SQL format, UTC)
  • requestTime – response time from the last test (ms), if available
  • info – additional information (error message, response details)
  • testsCount – number of tests from the very beginning
  • errorsCount – number of error results from the very beginning
  • pendingErrorsCount – number of current errors
  • lastErrorBeginStamp – date and time of the beginning of the current error status (UNIX timestamp)
  • ip – IP address of the target (if available)
  • ptr – reverse record (PTR) of the target (if available)
  • nextStamp – approximate date and time of the next test (UNIX timestamp)
  • warnings – array of additional warnings (certificate expiration, IP on blocklists, less severe response errors etc.)