Alertra API v1.1

Quickstart

curl https://api.alertra.com/v1.1/hello

Hello 192.168.1.10
The time is 2013-02-25 22:38:03 UTC.
Have a splendid day.

Get a list of your devices:

>>> import requests
>>> url = 'https://api.alertra.com/v1.1/devices'
>>> headers = {'Alertra-API-Key': '{YOUR-API-KEY}'}
>>> r = requests.get(url, headers=headers)
>>> r.json()[0]
{
    "Status": "Up",
    "URL": "https://www.alertra.com",
    "Method": "HTTP",
    "Frequency": 60,
    "LastCheckResult": "200 OK",
    "StatusSince": "2000-01-01T00:00:38-06:00",
    "ShortName": "WWW",
    "FullName": "Alertra WWW site",
    "device_id": "7af3be92c14d8e9a5f62d1c8b3e7094567d2891acd345f2e"
}

Get check data for one of your devices:

>>> import requests
>>> url = 'https://api.alertra.com/v1.1/devices/{device_id}/checks'
>>> headers = {'Alertra-API-Key': '{YOUR-API-KEY}'}
>>> r = requests.get(url, headers=headers)
>>> r.json()
[
  {
    "check_id": "9df4ce83b25e9f0a6e73d2b9c4f8105678e3902bde456g3f",
    "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/{device_id}/start-maintenance'
>>> payload = {'Duration': '02:00'}
>>> headers = {'Alertra-API-Key': '{YOUR-API-KEY}', 'Content-Type': 'application/json'}
>>> r = 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
2000-01-01T00:00:00Z

This is designed so that timestamps returned by the API can easily be passed back to the API on subsequent calls.

API Scope

If you need the API to do something that is not currently supported, just let us know and we can probably help you out.

Reference

Checks

• GET /checks/{check_id}
  Get the data for a check_id.

• GET /checks/{check_id}/extended
  Get the extra data for a check_id.

Devices

• POST /devices
  Post a new device.

  Parameter	Description
  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.

  Parameter	Description
  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}
  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}
  Get the settings for a device.

• DELETE /devices/{device_id}
  Delete a device.

• GET /devices/{device_id}/checks
  Get up to 100 checks for a device.

  Parameter	Description
  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}/events
  Get the most recent events for a device.

  Parameter	Description
  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}/start-maintenance
  Start maintenance for a device.

  Parameter	Description
  Duration	“HH:MM”. Optional, default=“01:00”

• PUT /devices/{device_id}/stop-maintenance
  Stop maintenance for a device.

• GET /devices/{device_id}/uptime
  Get 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.

  Parameter	Description
  Timestamp1	Begin time
  Timestamp2	End time. Optional, default=Current time

  Response example:

  
    {
      "Uptime": {
        "UpSeconds": 3600941,
        "DownSeconds": 386,
        "MaintenanceSeconds": 0,
        "Outages": 1
      }
    }       
    

Tags

• POST /tags
  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.

  Parameter	Description
  Name	Tag name

• GET /tags
  Get the list of tags.

• PUT /tags/{tag_id}
  Update a tag. Parameters are the same as for POST /tags.

• DELETE /tags/{tag_id}
  Delete a tag.

• GET /tags/{tag_id}
  Get a tag and its devices.

• PUT /tags/{tag_id}/devices/{device_id}
  Attach a tag to a device.

• DELETE /tags/{tag_id}/devices/{device_id}
  Remove a tag from a device.