API Documentation

Dog Ear's API lets you check server status, add, remove, and update servers. We also support alerts via webhooks (paid plans only), which can be configured when creating or editing a server. This API is a simple HTTP API that expects and returns JSON.

Important Notes

You must set the "Content-Type" header to "application/json." e.g. Content-Type: application/json

This API uses HTTP token based authentication. The token is your api key, which must be set as the value of the "Authorization" header.

Sign in to see your api key.

All requests must set an "Authorization" header. e.g. Authorization: Token token={your api key}.

The root URL for the API is https://dogear.io/api/v1. The endpoints below should concatenated with this URL.

Endpoints

GET /servers

Returns a list of servers and their latest status.

Sample response:

{
  "servers": [
    {
      "id": 1,
      "user_id": 1,
      "name": "google",
      "url": "http://google.com",
      "http_method": "GET",
      "headers": [
        {
          "name": "User-Agent",
          "value": "dogear.io / woof / 1.0.0"
        }
      ],
      "body": "",
      "alert_phone_numbers": [],
      "alert_emails": [
        "you@yourdomain.com"
      ],
      "last_status": "up",
      "last_status_checked_at": "2016-05-01T17:56:04.493Z",
      "check_interval": 5,
      "disable_ssl_validation": false,
      "webhook_url": null
    },
    ...
  ]
}

POST /servers

Adds a new server (URL) to be monitored by Dog Ear. Returns an error if you're at your plan's limit.

Parameters:

Parameter Name	Type	Required	Notes
name	string	Yes	The display name of the server
url	string	Yes	The URL to monitor
http_method	string	Yes	Possible values are "GET" or "POST"
headers	array of hashes	No	See sample for expected format
body	string	No	Only used when http_method is "POST"
alert_emails	array	Yes*	See sample for expected format. One of alert emails, phone numbers, or webhook URL is required.
alert_phone_numbers	array	Yes*	See sample for expected format. One of alert emails, phone numbers, or webhook URL is required. Only used by paid plans.
webhook_url	string	Yes*	Dog Ear will POST to this URL if your server status changes from down to up or up to down. One of alert emails, phone numbers, or webhook URL is required. Only used by paid plans.
disable_ssl_validation	boolean	No	False by default. This should only be used if you're using a self-signed certificate.

These parameters must be wrapped in a "server" object that is passed as the request body. For example:

{
  "server": {
      "name": "google.com",
      "url": "http://google.com",
      "http_method": "GET",
      "headers": [
        {
          "name": "User-Agent",
          "value": "dogear.io / woof / 1.0.0"
        }
      ],
      "alert_emails": ["you@yourdomain.com"]
    }
}
      

Sample response:

{
  "server": {
    "id": 13,
    "user_id": 1,
    "name": "google",
    "url": "http://google.com",
    "http_method": "GET",
    "headers": [
      {
        "name": "User-Agent",
        "value": "dogear.io / woof / 1.0.0"
      }
    ],
    "body": null,
    "created_at": "2016-05-13T02:09:53.215Z",
    "updated_at": "2016-05-13T02:09:53.215Z",
    "alert_phone_numbers": ["12225551212"],
    "alert_emails": ["you@yourdomain.com"],
    "last_status": "unknown",
    "last_status_checked_at": "2016-05-13T02:07:53.214Z",
    "check_interval": 5,
    "disable_ssl_validation": null,
    "webhook_url": null
  }
}
      

Note: The status will always be "unknown" immediately after creation. The status will be updated once Dog Ear has checked checked your URL for the first time.

PUT or PATCH /servers/{id}

Updates the server with the specified id.

Parameters:

Parameter Name	Type	Required	Notes
id	integer	Yes	part of URL

See the documentation for creating a server for a list of all parameters. You can pass only the parameters you want to change. For example, you can update only the name of a server. Note that any array or hash fields that are passed (e.g. headers, alert_emails, alert_phone_numbers) will be replaced wholesale on update.

Sample Response:

See the documentation for creating a server for a sample response.

DELETE /servers/{id}

Deletes the server with the specified id.

Parameters:

Parameter Name	Type	Required	Notes
id	integer	Yes	part of URL

Sample Response:

HTTP 204 (no content) if successful. HTTP 400 (bad request) if the server was not found.

POST /servers/notify/{id}

Programmatically notifies contacts on the given server (except webhooks) with the specified message

Parameters:

Parameter Name	Type	Required	Notes
id	integer	Yes	part of URL
message	string	Yes	Message to send via SMS, Slack, and Email

Sample Response:

{
  "message": "notification_success",
  "human_message": "Successfully notified oncall for server id 18"
}
      

HTTP 200 if successful. HTTP 400 (bad request) otherwise.