Monitoring API
An Application Programming Interface (API) to help users retrieve information about their account, monitoring checks, and their current status. You can integrate our monitoring system into your application or automatically process new events for monitored domains and services.
API activation
Access to the API can be activated in the WEDOS administration, which you reach via client.wedos.com in the details of the specific domain for which you have activated this additional service.
In the administration, choose the Settings -> API Settings section. 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 and all data is encoded in UTF-8.
Every response carries a requestId entry 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. Authentication uses two HTTP headers sent with every request:
| 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 basic call to a method called ping, which simply checks that the connection and authentication work.
Request
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
Response
{
"stamp": 1613393366,
"time": "2021-02-15 13:49:26",
"userId": 1000,
"requestId": "3bb52d4d22.1613393366.2811.82063"
}
On error the HTTP server returns a status 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 checks). These methods share common functions, input parameters and output data. The result 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 |
totalCount | number of all items |
Example response (the individual items are omitted here):
{
"results": [
...
],
"page": 1,
"count": 10,
"filteredCount": 18,
"totalCount": 624,
"requestId": "..."
}
This response means there are 624 items in total for the current user (for example checks), of which 18 match the active filter(s), and the first 10 items were returned (first page, paging after 10 items).
One or more filters can be passed as GET parameters in a list request; only the matching items are returned. List items can be paged, that is returned only in certain ranges. The API allows a maximum of 1000 items per call and the default paging is 100 items.
The following GET parameters control paging and 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):
Checks list
A method called checks fetches the list of monitored services in your account.
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:
Meaning of the items in the response:
| Field | Meaning |
|---|---|
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 | seconds in error state in the last 24 hours |
avgTime_1d | average response time in the last 24 hours (seconds) |
uptime_7d | uptime in the last 7 days (percent) |
errorSeconds_7d | seconds in error state in the last 7 days |
avgTime_7d | average response time in the last 7 days (seconds) |
uptime_30d | uptime in the last 30 days (percent) |
errorSeconds_30d | seconds 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:
| Status | Meaning |
|---|---|
unknown | test not performed yet |
ok | everything is okay |
slow | response was successful, but slow |
response_timeout | connection succeeded, but timed out 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 run the test, usually because the target resolves to an IP address in a private range |
unverified | you did not verify ownership of the website you want to monitor (applies to HTTP checks) |
invalidStatus | other invalid status of a monitored service |
Check detail
A check method shows more details about one particular check (monitored service). You add the check ID to the URL, for example:
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"
}
Additional information about the check:
| Field | Meaning |
|---|---|
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 | start 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.) |
Build it into your stack.
Create an account, add a check and generate your API key in a couple of minutes.
Start free