WEDOS EWM – API documentation
WEDOS Early Warning and Monitoring (EWM) offers an API, a programmatic interface through which users can retrieve information about their monitored domains, service checks and their current status. You can program the integration of monitoring with your application or automatically track new events for monitored domains and services.
API activation
Access to the API can be activated in the EWM administration, which you reach via client.wedos.com in the details of the specific domain for which you have this paid service active. In the EWM administration choose Settings -> API Settings. Activation generates an API key (similar to a password), which you then use for authentication in API communication.
Basic information
Communication with the API runs over HTTPS using the GET method. Some methods accept parameters in the URL (GET parameters).
All methods return a response as a JSON object. All data in the response is encoded in UTF-8.
Every response contains a requestId item that uniquely identifies the request. With this identifier we can locate the specific communication in our log if a problem or question arises.
The API is located at https://api.wedos.online/mon/ followed by the name of the specific method.
User authentication uses special HTTP headers – every request includes the API key ID (X-Auth-Id) and the API key (X-Auth-Key).
| Header | Value |
|---|---|
X-Auth-Id | your API key ID |
X-Auth-Key | your API key |
The API has the following limits:
- max. 1000 requests per hour from one IP address
- max. 1000 requests per hour from one user
Hello World!
This is a call to a method called ping, which lets you easily verify that API communication and authentication work.
Request
GET /mon/ping HTTP/1.1 Host: api.wedos.online Accept: application/json X-Auth-Id: me@example.com X-Auth-Key: MY_API_KEY
The response should look something like this
{
"stamp": 1613393366,
"time": "2021-02-15 13:49:26",
"userId": 1000,
"requestId": "3bb52d4d22.1613393366.2811.82063"
}On error the server returns an HTTP response code other than 200 and the response body specifies the error: the error code and its description. Example:
{
"error": {
"code": "C507",
"error": "Authentication failed"
},
"requestId": "1495544185.1615.8422"
}Lists, filtering, paging
Some API methods return a list of items (for example a list of domains). These methods share common functions, input parameters and output data.
The result of list-reading methods always includes the following items:
| Item | Meaning |
|---|---|
results | array of objects with the individual list items |
page | page number (see paging below) |
count | number of returned items |
filteredCount | number of all items that match the current filter (see filtering below) |
totalCount | number of all items |
Example response (the individual items are omitted here):
{
"results": [
...
],
"page": 1,
"count": 10,
"filteredCount": 18,
"totalCount": 624,
"requestId": "..."
}This particular response means that there are 624 items in total in the database for the current user (for example domains), of which 18 match the set filters, and the first 10 were returned (first page, paging by 10 items).
One or more filters can be passed in a list request. They are given as GET parameters. The matching items are then selected and returned.
List items can be paged, that is returned only in certain counts. 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:
| Parameter | Meaning |
|---|---|
page | page number (default 1) |
count | number of returned items, i.e. page size (default 100) |
Example of listing 10 items on the second page (items 11 to 20):
List of domains
A method called domains lets you get a list of your domains monitored by EWM.
Request URL:
Example response
{
"results": [
{
"ID": 24,
"name": "example.com",
"status": "warning",
"checks": {
"domain": { "checkId": null },
"http": { "checkId": 5056 },
"dnsauth": { "checkId": 5052 },
"dnssec": { "checkId": 5178 },
"mx": { "checkId": 5093 },
"smtp": { "checkId": 5066 },
"pop3": { "checkId": 5095 },
"imap": { "checkId": 5098 },
"ftp": { "checkId": 5183 },
"ssh": { "checkId": 5184 },
"spf": { "checkId": 5110 }
}
}
],
"page": 1,
"count": 1,
"filteredCount": 1,
"totalCount": 1,
"requestId": "3bb52d4d22.1615325171.8202.150654"
}Here you can see the overall status of all your monitored domains and the list of checks performed for each domain.
If you want details, you can get the detail of a specific domain using the domain method, or the detail of a specific check using the check method (use the checkId value as the identifier of the specific check).
Domain detail
To get detailed information about one specific domain and its checks (monitored services), use the domain method.
Example response (output was shortened)
{
"domain": {
"ID": 24,
"name": "example.com",
"status": "warning",
"checks": {
"domain": { "checkId": null },
"http": {
"checkId": 5056,
"status": "ok",
"name": "example.com HTTP",
"type": "http",
"period": 60,
"fullTarget": "https://example.com/",
"domainId": 24,
"statusStamp": 1613140656,
"statusDate": "2021-02-12 14:37:36",
"createdStamp": 1604348089,
"createdDate": "2020-11-02 20:14:49",
"uptime_1d": 100,
"errorSeconds_1d": 0,
"avgTime_1d": 111,
"uptime_7d": 100,
"errorSeconds_7d": 0,
"avgTime_7d": 109,
"uptime_30d": 99.994,
"errorSeconds_30d": 57,
"avgTime_30d": 114,
"warningsCount": 0
},
"dnsauth": { ... },
"dnssec": { ... },
"mx": { ... },
"smtp": { ... },
"pop3": { ... },
"imap": { ... },
"ftp": { ... },
"ssh": { ... },
"spf": { ... }
}
},
"requestId": "3bb52d4d22.1615325829.4246.150888"
}Meaning of the individual items in the response:
| Item | Meaning |
|---|---|
ID | domain ID |
name | domain name |
checkId | check ID |
type | check type (ping, http, dns, smtp, …) |
period | test interval (seconds) |
fullTarget | host name or domain name of the target |
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 (UNIX timestamp) |
createdDate | check creation (SQL format, UTC) |
uptime_1d | uptime in the last 24 hours (percent) |
errorSeconds_1d | duration of error states in the last 24 hours (seconds) |
avgTime_1d | average response time in the last 24 hours (seconds) |
uptime_7d | uptime in the last 7 days (percent) |
errorSeconds_7d | duration of error states in the last 7 days (seconds) |
avgTime_7d | average response time in the last 7 days (seconds) |
uptime_30d | uptime in the last 30 days (percent) |
errorSeconds_30d | duration of error states in the last 7 days (seconds) |
avgTime_30d | average response time in the last 30 days (seconds) |
warningsCount | number of active warnings |
The status can be:
| Status | Meaning |
|---|---|
unknown | test not performed yet |
ok | everything is okay |
slow | response was okay, but slow |
response_timeout | connection was established, but timed out waiting for a response |
down | connection failed |
response_error | invalid response |
maintenance | the check is in planned maintenance |
paused | the check is paused, no tests are performed |
disabled | the check was disabled by an administrator |
denied | monitoring refused to run the test – usually it means you are trying to connect to an IP address in a private range |
invalidStatus | another invalid status of the monitored service |
Check detail
If you want to see even more detailed information about a specific check of a specific domain, the check method is available. Add the check ID to the URL, e.g.:
Example response
{
"check": {
"ID": 5178,
"name": "example.com DNSSEC",
"type": "dnssec",
"period": 600,
"fullTarget": "example.com",
"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": "example.com/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"
}Meaning of the additional items in the response:
| Item | Meaning |
|---|---|
lastTestStamp | last test (UNIX timestamp) |
lastTestDate | last test (SQL format, UTC) |
requestTime | response time in the last test (ms), if available |
info | additional information (error message, response detail) |
testsCount | total number of tests performed since the beginning |
errorsCount | total number of errors since the beginning |
pendingErrorsCount | number of errors within the current error state |
lastErrorBeginStamp | start of the current error state (UNIX timestamp) |
ip | IP address of the target (if available) |
ptr | reverse record of the target (PTR) (if available) |
nextStamp | approximate time of the next test (UNIX timestamp) |
warnings | list of additional warnings (upcoming certificate expiration, IP on blocklists, less severe response errors, etc.) |
Build it into your infrastructure.
Create an account, add a check and generate your API key in a couple of minutes.
Start free