NAV Navbar
shell

Introduction

This document contains details about the Observery API. You can use our API to access Observery API endpoints, which allows you to get information about your account's checks, contacts, ..., as well as programmatically create new and manage existing checks, contacts, ...

On the right side of this page you can view cURL examples, complete with JSON responses. We don't currently provide libraries to integrate with our API, but we've tried to keep things simple and standards-based with our RESTful API with JSON responses, so interfacing with our API in your language of choice should be straightforward.

Authentication

To authorize, use this code:

# Use cURL's "--user" flag to authenticate your requests
# Your language of choice almost certainly provides
# the capabaility to use Basic-Auth
curl --user "api_username:api_password" "api_endpoint_here"

Replace api_username and api_password with your account-specific values.

Observery uses Basic-Auth to authorize access to the API. You can acquire your API username and password on the Account Profile page.

Observery expects your API username and password to be included in all API requests. Failure to include API username and password will result in failure. Basic-Auth is ubiquitous and your language / library should provide support for Basic-Auth.

Successful Response

Example Successful Response:

{
    "success": true,
    "result": {
      ...
    }
}

All responses from the Observery API should contain a boolean success field which indicates whether or not the request was successful. A value of true indicates that the call was successful. When successful, the JSON response will contain the result key which will contain a JSON object with the results of this request.

Failure Response

Example Failure Response:

{
    "success": false,
    "reason": "access not authorized"
}

Failure responses will contain a success value of false, as well as a reason or reasons key with details about why the request failed.

Validation Failure Response

Failure Response Due to Validation:

{
  "success": false,
  "reasons": [
    {
      "field": "name",
      "error": "this field is required"
    },
    {
      "field": "host",
      "error": "this field is required"
    },
    {
      "field": "active",
      "error": "this field is required"
    },
    {
      "field": "interval",
      "error": "this field is required"
    }
  ]
}

When validation errors occur - for example, you try to create a new Check, but fail to include several fields - the response will contain an array of reasons detailing why your request failed. Each array entry will indicate the field and related error.

Checks

Before getting into details about the specific API calls available for checks, lets cover some of the types/values/fields/... we'll refer to for those API calls.

Check Types

Type Description
http Check a webpage via HTTP or HTTPS
ping Ping a server (ICMP)
ssh Check SSH access on a server
ftp Check FTP access on a server
pop Check POP access on a server
smtp Check SMTP access on a server
imap Check IMAP saccess on a server
cert Check SSL Cert validity / expiration

Check State

State Description
up Check is UP
down Check is DOWN
waiting Check was recently created and is waiting to be checked

Check Fields

Type Type Description
url string only used for http - url of page
host string domain or ip of host
port int always optional port
secure boolean whether to use the secure version of the protocol
username string username for protocol (basic-auth for http)
password string password for protocol (basic-auth for http)
httpHeaders string headers to include for http check
sendData string data to send for check (POST data for http)
certExpirationDays int number of days till CERT expiration that should yield in a down status

Type to Field Availability

Field Required Optional
http url username, password, sendData, httpHeaders
ping host
ssh host port
ftp host username, password, port, secure
pop host port, secure
smtp host port, secure
imap host port, secure
cert host, certExpirationDays port

Get All Checks

curl "https://api.observery.com/api/v1/check" \
  --user "api_username:api_password"

The above command returns JSON structured like this:

{
    "success": true,
    "result": [
        {
            "id": "05eda5b175dc49b3bb5be084ae75dca6",
            "name": "Unreliable Site",
            "active": true,
            "type": "http",
            "state": "down",
            "since": "2019-04-04T01:48:26",
            "url": "https://neverworks.com"
        },
        {
            "id": "9aa054957c644a1c81fe25dd90be944a",
            "name": "Ping Test",
            "active": true,
            "type": "ping",
            "state": "waiting",
            "host": "pingtest.observery.com"
        },
        {
            "id": "8c3f147fa82545ba831ac7ea42f4b218",
            "name": "SSH Test",
            "active": true,
            "type": "ssh",
            "state": "waiting",
            "host": "sshtest.observery.com"
        }
    ]
}

This endpoint retrieves all Checks for your account.

HTTP Request

GET https://api.observery.com/api/v1/check

URL Parameters

In this context, the following URL parameters will filter the list of checks returned.

Parameter Type Description
type string see Check Types section above
name string case-insensitive check name comparison
state string See Check State section above

Response

Key Type Description
id int id of check
name string name of check
active boolean whether or not this check is active
type string as described at the top of this section
state string as described at the top of this section
since date/time UTC datetime when state last changed
url string configured url for this check (conditional)
host string configure host for this check (conditional)

Get Check Details

curl "https://api.observery.com/api/v1/check/05eda5b175dc49b3bb5be084ae75dca6" \
  --user "api_username:api_password"

The above command returns JSON structured like this:

{
    "success": true,
    "result": {
        "id": "05eda5b175dc49b3bb5be084ae75dca6",
        "name": "Unreliable Site",
        "type": "http",
        "state": "down",
        "since": "2019-04-04T01:48:26",
        "outageId": "ecf64bc344f7491792d542ea7bcbb3c8",
        "url": "https://neverworks.com",
        "active": true,
        "interval": 1,
        "emailNotificationDelay": 0,
        "smsNotificationDelay": 3,
        "inMaintenance": false,
        "maintenanceModeActive": false,
        "maintenanceSchedules": [
            {
                "days": "monday,wednesday,friday",
                "start": "00:00",
                "stop": "02:00",
                "timezone": "America/Chicago"
            },
            {
                "days": "saturday,sunday",
                "start": "00:30",
                "stop": "01:00",
                "timezone": "America/Chicago"
            }
        ],        
        "contactIds": [
            "544b5952c24f4c888b3f10267e90238d",
            "1d2b1e58edbc4513aa6f791fede257c3",
            "f4236918174c4c46be5bceb173d8828c"
        ],
        "contacts": [
            {
                "id": "544b5952c24f4c888b3f10267e90238d",
                "name": "Cell Phone"
            },
            {
                "id": "1d2b1e58edbc4513aa6f791fede257c3",
                "name": "Email"
            },
            {
                "id": "f4236918174c4c46be5bceb173d8828c",
                "name": "DisabledTest"
            }
        ]
    }
}

This endpoint retrieves details for a specific Check.

HTTP Request

GET https://api.observery.com/api/v1/check/:id

URL Parameters

Parameter Description
id The ID of the Check to retrieve

Response

The response contains full details for the requested Check as well as basic details about the checks mapped to this Check. You can retrieve full check details with the appropriate check API endpoint.

Key Type Description
id int id of check
name string name of check
type string as described at the top of this section
state string as described at the top of this section
since date/time UTC datetime when state last changed
outageId int id of current outage if check is down
active boolean whether or not this check is active
interval int interval (in minutes) this check is ran
(type fields) * refer to Check Fields and Type to Field Availability sections at the top of this section to see which fields could be included for this type
emailNotificationDelay int minute(s) delay before email notifications are sent
smsNotificationDelay int minute(s) delay before sms notifications are sent
inMaintenance boolean whether or not this check is currently in maintenance, either due to this check's maintenance schedules or if maintenance mode has been activated.
maintenanceModeActive boolean whether or not maintenance mode has been activated (not related to check maintenance schedules)
maintenanceSchedules array maintenance schedules configured for this check
      days string comma-separated list of days
      start time start time in this maintenance schedule's timezone
      stop time stop time in this maintenance schedule's timezone
      timezone string timezone for this maintenance schedule
contactIds string[] ids of mapped contacts
contacts array details about mapped contacts
      id int contact id
      name string contact name

Create a Check

curl https://api.observery.com/api/v1/check \
  -d "type=ping&name=test&active=true&" \
  -d "interval=3&host=ping.observery.com" \
  -X POST \
  --user "api_username:api_password"

The above command returns JSON structured like this:

{
    "success": true,
    "result": {
        "id": "afa10ad2014249d59a6b951e6c75db68",
        "message": "successfully created"
    }
}

This endpoint creates a new Check.

HTTP Request

POST https://api.observery.com/api/v1/check

URL Parameters

Parameter Type Description
type string as described at the top of this section
name string name for this check
active boolean whether or not this check is active
interval int interval (in minutes) this check is ran
contacts string comma-separated list of checks ids to map to this check
(type fields) * refer to Check Fields and Type to Field Availability sections at the top of this section to see which fields could be included for this type

Response

Key Type Description
id int id of newly created Check
message string should read 'successfully created'

Update a Check

curl "https://api.observery.com/api/v1/check/afa10ad2014249d59a6b951e6c75db68?active=false&name=DisabledTest" \
  -X PUT \
  --user "api_username:api_password"

The above command returns JSON structured like this:

{
    "success": true,
    "result": {
        "id": "afa10ad2014249d59a6b951e6c75db68",
        "message": "successfully updated"
    }
}

This endpoint updates an existing Check.

HTTP Request

PUT https://api.observery.com/api/v1/check/:id

URL Parameters

Parameter Type Description
id int (part of URL) id of check you want to update
name string name for this check
active boolean whether or not this check is active
interval int interval (in minutes) this check is ran
contacts string comma-separated list of checks ids to map to this check
(type fields) * refer to Check Fields and Type to Field Availability sections at the top of this section to see which fields could be included for this type

Response

Key Type Description
id int id of updated Check
message string should read 'successfully updated'

Delete a Check

curl "https://api.observery.com/api/v1/check/afa10ad2014249d59a6b951e6c75db68" \
  -X DELETE \
  --user "api_username:api_password"

The above command returns JSON structured like this:

{
  "success": true,
  "result" : "successfuly deleted"
}

This endpoint deletes a specific Check.

HTTP Request

DELETE https://api.observery.com/api/v1/check/:id

URL Parameters

Parameter Description
id id of the Check to delete

Contacts

Get All Contacts

curl "https://api.observery.com/api/v1/contact" \
  --user "api_username:api_password"

The above command returns JSON structured like this:

{
    "success": true,
    "result": [
        {
            "id": "1d2b1e58edbc4513aa6f791fede257c3",
            "type": "email",
            "name": "Test Email Contact",
            "verified": true,
            "enabled": true,
            "email": "test@observery.com",
            "format": "long",
            "checkMappingCount": 11
        },
        {
            "id": "544b5952c24f4c888b3f10267e90238d",
            "type": "sms",
            "name": "Cell Phone",
            "verified": true,
            "enabled": true,
            "number": "+15554441234",
            "checkMappingCount": 8
        }
    ]
}

This endpoint retrieves all contacts for your account. No filtering options are currently available.

HTTP Request

GET https://api.observery.com/api/v1/contact

Response

Key Type Description
id int id of contact
type string 'email' or 'sms'
name string name of contact
verified boolean whether or not this contact is verified
enabled boolean whether or not this contact is enabled
email string only applies to type = email
number string only applies to type = sms
format string 'short' or 'long' - only applies to email
checkMappingCount int # of checks mapped to this contact

Get Contact Details

curl "https://api.observery.com/api/v1/contact/1d2b1e58edbc4513aa6f791fede257c3" \
  --user "api_username:api_password"

The above command returns JSON structured like this:

{
    "success": true,
    "result": {
        "id": "1d2b1e58edbc4513aa6f791fede257c3",
        "type": "email",
        "name": "Email",
        "verified": false,
        "enabled": true,
        "email": "test@observery.com",
        "format": "long",
        "checkMappingCount": 8,
        "checkIds": [
            "dcd4525e8e6f11e9a59f14c213ed728e",
            "f5f8a0788e6f11e9a59f14c213ed728e",
            "d1cc86d48e6e11e9a59f14c213ed728e",
            "cfe30b728e6e11e9a59f14c213ed728e",
            "e39540e48e6f11e9a59f14c213ed728e",
            "f6a6fd1c8e6f11e9a59f14c213ed728e",
            "cf3f79628e6e11e9a59f14c213ed728e",
            "e4f0ca4e8e6f11e9a59f14c213ed728e"
        ],
        "checks": [
            {
                "id": "dcd4525e8e6f11e9a59f14c213ed728e",
                "name": "Observery Service - H",
                "type": "http"
            },
            {
                "id": "cf3f79628e6e11e9a59f14c213ed728e",
                "name": "Client Site",
                "type": "http"
            },
            {
                "id": "cfe30b728e6e11e9a59f14c213ed728e",
                "name": "Observery Service - A",
                "type": "http"
            },
            {
                "id": "d1cc86d48e6e11e9a59f14c213ed728e",
                "name": "Observery Service - C",
                "type": "http"
            },
            {
                "id": "e39540e48e6f11e9a59f14c213ed728e",
                "name": "Observery Service - I",
                "type": "http"
            },
            {
                "id": "e4f0ca4e8e6f11e9a59f14c213ed728e",
                "name": "Observery Service - K",
                "type": "http"
            },
            {
                "id": "f5f8a0788e6f11e9a59f14c213ed728e",
                "name": "pingtest",
                "type": "ping"
            },
            {
                "id": "f6a6fd1c8e6f11e9a59f14c213ed728e",
                "name": "pingtest",
                "type": "ping"
            }
        ]
    }
}

This endpoint retrieves details for a specific Contact.

HTTP Request

GET https://api.observery.com/api/v1/contact/:id

URL Parameters

Parameter Description
id The ID of the contact to retrieve

Response

The response contains full details for the requested contact as well as basic details about the checks mapped to this contact. You can retrieve full check details with the appropriate check API endpoint.

Key Type Description
id int id of contact
type string 'email' or 'sms'
name string name of contact
verified boolean whether or not this contact is verified
enabled boolean whether or not this contact is enabled
email string only applies to type = email
number string only applies to type = sms
format string 'short' or 'long' - only applies to email
checkMappingCount int # of checks mapped to this contact
checkIds string[] ids of checks mapped to this contact
checks array details about mapped checks
      id int check id
      name string check name
      type string check type

Create a Contact

curl https://api.observery.com/api/v1/contact \
  -d "type=email&enabled=true&name=test&" \
  -d "email=test@observery.com&format=long&checks=dcd4525e8e6f11e9a59f14c213ed728e" \
  -X POST \
  --user "api_username:api_password"

The above command returns JSON structured like this:

{
    "success": true,
    "result": {
        "id": "f4236918174c4c46be5bceb173d8828c",
        "message": "successfully created"
    }
}

This endpoint creates a new contact.

HTTP Request

POST https://api.observery.com/api/v1/contact

URL Parameters

Parameter Type Description
type string 'email' or 'sms'
name string name for this contact
email string email address for this contact - only when type=email
number string sms number for this contact - only when type=sms
enabled boolean whether or not this contact should be enabled
format string 'short' or 'long' - only when type=email
checks string comma-separated list of checks ids to map to this contact

Response

Key Type Description
id int id of newly created contact
message string should read 'successfully created'

Update a Contact

curl "https://api.observery.com/api/v1/contact/f4236918174c4c46be5bceb173d8828c?enabled=false&name=DisabledTest" \
  -X PUT \
  --user "api_username:api_password"

The above command returns JSON structured like this:

{
    "success": true,
    "result": {
        "id": "f4236918174c4c46be5bceb173d8828c",
        "message": "successfully updated"
    }
}

This endpoint update an existing contact.

HTTP Request

PUT https://api.observery.com/api/v1/contact/:id

URL Parameters

Parameter Type Description
id int (part of URL) id of contact you want to update
name string name for this contact
enabled boolean whether or not this contact should be enabled
format string 'short' or 'long' - only when type=email
checks string comma-separated list of checks ids to map to this contact

Response

Key Type Description
id int id of updated contact
message string should read 'successfully updated'

Delete a Contact

curl "https://api.observery.com/api/v1/contact/f4236918174c4c46be5bceb173d8828c" \
  -X DELETE \
  --user "api_username:api_password"

The above command returns JSON structured like this:

{
  "success": true,
  "result" : "successfuly deleted"
}

This endpoint deletes a specific Contact.

HTTP Request

DELETE https://api.observery.com/api/v1/contact/:id

URL Parameters

Parameter Description
id id of the contact to delete

Outages

Get Recent Outages

curl "https://api.observery.com/api/v1/outage" \
  --user "api_username:api_password"

The above command returns JSON structured like this:

{
    "success": true,
    "result": [
        {
            "id": "57fddb6a5500485cb64a23e7e58eeab9",
            "checkId": "05eda5b175dc49b3bb5be084ae75dca6",
            "checkName": "Client Site",
            "ongoing": true,
            "start": "2019-04-04T01:48:26",
            "duration": 5532375736,
            "durationFriendly": "64d 46m"
        },
        {
            "id": "80ddaba5d98344159d2c60da13c8b8cd",
            "checkId": "05eda5b175dc49b3bb5be084ae75dca6",
            "checkName": "Client Site",
            "ongoing": false,
            "start": "2019-03-28T12:54:02",
            "stop": "2019-03-28T12:55:01",
            "duration": 59000,
            "durationFriendly": "1m"
        },
        {
            "id": "2efb9b7d8f2a46338584c00c1ef55b5f",
            "checkId": "9aa054957c644a1c81fe25dd90be944a",
            "checkName": "Observery Service - A",
            "ongoing": false,
            "start": "2019-03-25T14:31:01",
            "stop": "2019-03-25T14:32:01",
            "duration": 60000,
            "durationFriendly": "1m"
        }
    ]
}

This endpoint retrieves the 100 most recent Outages for your account.

HTTP Request

GET https://api.observery.com/api/v1/outage

Response

Key Type Description
id int id of outage
checkId int id of outage's check
checkName string name of outage's check
ongoing boolean whether or not the outage is still occurring
start date/time when the outage started
stop date/time when the outage stopped (if applicable)
duration int length of outage in milliseconds
durationFriendly string human-friendly representatino of duration

Get Outage Details

curl "https://api.observery.com/api/v1/outage/57fddb6a5500485cb64a23e7e58eeab9" \
  --user "api_username:api_password"

The above command returns JSON structured like this:

{
    "success": true,
    "result": {
        "id": "57fddb6a5500485cb64a23e7e58eeab9",
        "checkId": "05eda5b175dc49b3bb5be084ae75dca6",
        "checkName": "Client Site",
        "ongoing": true,
        "start": "2019-04-04T01:48:26",
        "duration": 5533429394,
        "durationFriendly": "64d 1h 4m",
        "responseTime": 31000,
        "details": "Timed Out"
    }
}

This endpoint retrieves details for a specific outage.

HTTP Request

GET https://api.observery.com/api/v1/outage/:id

URL Parameters

Parameter Description
id The ID of the outage to retrieve

Response

The response contains full details for the requested outage as well as basic details about the Outages mapped to this outage. You can retrieve full outage details with the appropriate outage API endpoint.

Key Type Description
id int id of outage
checkId int id of outage's check
checkName string name of outage's check
ongoing boolean whether or not the outage is still occurring
start date/time when the outage started
stop date/time when the outage stopped (if applicable)
duration int length of outage in milliseconds
durationFriendly string human-friendly representation of duration
responseTime int response time in millseconds
details string details about the outage
shell