Alertra API v1.1
Alertra API v1.1¶
Quickstart¶
Using curl, plug your API key in (leave out the angle brackets):
$ curl https://api.alertra.com/v1.1/hello?api_key=<YOUR-API-KEY>
Hello 192.168.1.10
Using key: <YOUR-API-KEY>
Key type: API
Auth level: UW
HTTP Auth: No
The time is 2013-02-25 22:38:03 UTC.
Have a splendid day.
Paste this to your browser to get your device list:
https://api.alertra.com/v1.1/devices?api_key=<YOUR-API-KEY>&fmt=xml
Get check data for one of your devices using Python and the excellent Requests library:
>>> import requests
>>> url = 'https://api.alertra.com/v1.1/devices/<YOUR-DEVICE-ID>/checks'
>>> headers = {'Alertra-API-Key': '<YOUR-API-KEY>'}
>>> r = requests.get(url, headers=headers)
>>> r.json()
[
{
"check_id" : "<CHECK_ID>",
"Location" : "Stockholm SWE",
"Timestamp" : "2014-02-11T20:30:37-05:00",
"BlockTime" : 0,
"ConnectTime" : 0,
"DNSTime" : 0,
"SSLTime" : 0,
"TTFB" : 0,
"TTLB" : 3520.77,
"RequestTime" : 3520.77392578125,
"Kbps" : 0,
"PerfStat" : "Ok",
"ResultCode" : 1,
"DataSize" : 0
}
]
Put a device into maintenance for two hours:
>>> import json
>>> import requests
>>> url = 'https://api.alertra.com/v1.1/devices/<YOUR-DEVICE-ID>/start-maintenance'
>>> payload = {'Duration': '02:00'}
>>> headers = {'Alertra-API-Key': '<YOUR-API-KEY>', 'Content-Type': 'application/json'}
>>> requests.put(url, data=json.dumps(payload), headers=headers)
>>> r.status_code
200
Your API Key¶
Please contact support to obtain an API key for your account. You may want to use different keys for different applications. You can have as many as you want.
Caution
Your API key is a secret and should not be shared with anyone. Anyone who has your key will be able to access your account configuration and data. If your key is ever compromised, we can delete it and give you a new one.
Requests¶
HTTP/1.1 methods GET, POST, PUT and DELETE are supported.
Location¶
The API is located at api.alertra.com. SSL is required. URLs must include the API version:
https://api.alertra.com/v1.1/devices
Authentication¶
It’s not really necessary or helpful, but you can specify a username and password when you request your key. The API will require an HTTP Basic Authentication header to be included with each request.
Authorization: Basic USER:PASS
Important
USER:PASS must be base64 encoded.
Identification¶
Your account is identified based on the presence of this header in the HTTP request:
Alertra-API-Key: <YOUR-API-KEY>
Or, by using a query string parameter in the URL:
api_key=<YOUR-API-KEY>
Which is better? We recommend sending the key as a header for increased security.
Authorization¶
API keys have authorization levels:
- UW (User Writer): Access to view/modify.
- UR (User Reader): Access to view only.
When the API receives a request, it verifies that the requestor is authorized for the access it is requesting. If it isn’t, an HTTP 400 error is returned (API error 1002, Authorization failed).
Request Body¶
Important
If a request includes data in the request body, the data must be in JSON format and the correct header must be included.
Content-Type: application/json
Responses¶
If the request is processed successfully, an HTTP 200 response is returned.
Otherwise, an HTTP 400 response is returned along with a JSON message body:
{
"code": 1002,
"message": "Access denied."
}
Data for most methods will be returned in JSON format with the header:
Content-Type: application/json
Add a fmt=xml query parameter to a URL to get the response in XML.
Add a fmt=csv query parameter to get the response in CSV (we’ll do our best, not all API responses fit the two-dimensional CSV model very well).
Add a filename=EXAMPLE.CSV parameter if you’re using a browser and you want to save the data as a file. Just replace EXAMPLE.CSV with whatever you want the file to be named.
Timestamps¶
All timestamps returned by the API will be converted to the account’s configured timezone and returned in ISO 8601 format.
Timestamp parameters sent to the API must be in ISO 8601 format:
2000-01-01T00:00:00-05:00 (U.S. Eastern Standard Time)
2000-01-01T00:00:00Z (UTC)
This is designed so that timestamps returned by the API can easily be passed back to the API on subsequent calls.
API Scope¶
This initial API release includes only the most important capabilities. If you have other needs, let us know and we can probably help you out.
Reference¶
- GET /checks/(check_id: string)¶
Get the data for a check_id.
- GET /checks/(check_id: string)/extended¶
Get the extra data for a check_id.
- POST /devices¶
{ "Method": "HTTP", "ShortName": "Example", "URL": "http://www.example.com" }
Add a new “device” to be monitored. A device can be a website, email server, router, etc.
Returns device_id for the new device.
Parameters: - Method – HTTP, PING, SMTP, POP3, MySQL, IMAP4, FTP, TELNET, SSH, NNTP, TCP, DNS, Script.
- URL – URL, hostname or custom script to monitor.
- ShortName – Give the device a name. Up to 8 letters, digits or ‘-‘.
- FullName – Description of the device. Optional.
- Frequency – Frequency of device checking in minutes: Optional: (1, 2, 5, 10, 20, 30, 60) default=5.
- Timeout – Number of seconds to wait for a response. Optional, 1-120, default=30.
- Retries – Number of retries after error before alert. Optional, 2-10, default=2.
- RetryDelay – Number of seconds to wait after error before trying again. Optional, 1-300, default=1.
- nschedule_id – Notification schedule to be used. Optional.
- mschedule_id – Maintenance schedule to be used. Optional.
- device_master_id – If the master device is already down, suppress alerts. Optional.
- GET /devices¶
Get a list of devices.
Parameters: - Filter – All, Ok, Down, Maint, tag_id.
- Offset – Skip Offset number of rows. Optional, default=0.
- Limit – Return up to Limit number of rows. Optional, default=25, max=100.
- PUT /devices/(device_id: string)¶
Update the settings for a monitored device. Parameters are the same as for POST /devices except Method cannot be changed for an existing device.
- GET /devices/(device_id: string)¶
Get the settings for a device.
- DELETE /devices/(device_id: string)¶
Delete a device.
- GET /devices/(device_id: string)/checks¶
Get up to 100 checks for a device.
Parameters: - Offset – Skip Offset number of rows. Optional, default=0.
- Limit – Return up to Limit number of rows. Optional, default=25, max=100.
- GET /devices/(device_id: string)/events¶
GET /devices/<DEVICE_ID>/events GET /devices/<DEVICE_ID>/events?Timestamp=2013-01-01+00:00:00+EST-500 GET /devices/<DEVICE_ID>/events?Offset=200&Limit=100
Get the most recent events for a device.
Parameters: - Timestamp – Return events prior to Timestamp. Optional, default=Current time.
- Offset – Skip Offset number of rows. Optional, default=0.
- Limit – Return up to Limit number of rows. Optional, default=25, max=100.
- PUT /devices/(device_id: string)/start-maintenance¶
{ "Duration": "01:30" }
Start maintenance for a device.
Parameters: - Duration – “HH:MM”. Optional, default=”01:00”.
- PUT /devices/(device_id: string)/stop-maintenance¶
Stop maintenance for a device.
- GET /devices/(device_id: string)/uptime¶
GET /devices/<DEVICE_ID>/uptime?Timestamp1=2014-01-01T00:00:00Get the uptime values for a device for the specified time period.
We calculate uptime percentage like this: (UpSeconds) / (UpSeconds + DownSeconds). This method excludes maintenance time which seems to be the fair way to do it.
Parameters: - Timestamp1 – Begin time.
- Timestamp2 – End time. Optional, default=Current time.
Response example:
{ "Uptime" : { "UpSeconds" : 3600941, "DownSeconds" : 386, "MaintenanceSeconds" : 0, "Outages" : 1 } }
{ "Name": "Critical" }
Create a new tag. Returns tag_id for the new tag.
Tags are useful for managing devices in a group, for example, to start maintenance for a group of devices.
Parameters: - Name – Tag name.
Get the list of tags.
Update a tag. Parameters are the same as for POST /tags.
Delete a tag.
Get a tag and its devices.
Attach a tag to a device.
Remove a tag from a device.
