Dead Man's Snitch

API Documentation

You can access and manage your snitches with Dead Man's Snitch's JSON API. You might use the API to build a custom monitoring dashboard or to automate your monitoring workflow by managing your snitches from scripts.

  1. Getting Started
  2. Snitches Reference
    1. Listing your Snitches
      1. Filtering Snitches by Tag
    2. Examining a Snitch
    3. Creating a Snitch
      1. Request Parameters
      2. Error Responses
    4. Editing a Snitch
      1. Adding one or more tags to a snitch
      2. Removing a tag from a snitch
      3. Changing tags on a snitch
    5. Pausing a Snitch
    6. Deleting a Snitch
  3. API Key Reference
    1. Fetching Your Key
      1. Error Responses
  4. Error Reference
    1. Everything That Can Go Wrong

Getting Started

You access the API using your API key. You can find your API key on your account page, or you can grab your key directly from the API with your username and password:

$ curl --user alice@example.com:password https://api.deadmanssnitch.com/v1/api_key
{
  "api_key": "_caeEiZXnEyEzXXYVh2NhQ"
}

Try it in your browser, then copy your key: https://api.deadmanssnitch.com/v1/api_key

Once you have your API Key, use it as the username for accessing any other API action. Leave the password blank (in curl, you do this by putting a : after the username). Let's take a look at our snitches:

$ curl -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches
[
  {
    "token": "c2354d53d2",
    "href": "/v1/snitches/c2354d53d2",
    "name": "Daily Backups",
    "tags": [
      "production",
      "critical"
    ],
    "status": "pending",
    "checked_in_at": "2014-01-01T12:00:00.000Z",
    "interval": "daily",
    "alert_type": "basic",
  },
  {
    "token": "c2354d53d2",
    "href": "/v1/snitches/c2354d53d2",
    "name": "Hourly Emails",
    "tags": [
    ],
    "status": "healthy",
    "checked_in_at": "2014-01-01T12:00:00.000Z",
    "interval": "hourly",
    "alert_type": "basic",
  }
]

With your API key from the last action, you can list your snitches in your browser: https://api.deadmanssnitch.com/v1/snitches

You can get more information about an individual snitch:

$ curl -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches/c2354d53d2
{
  "token": "c2354d53d2",
  "href": "/v1/snitches/c2354d53d2",
  "name": "Daily Backups",
  "tags": [
    "production",
    "critical"
  ],
  "status": "pending",
  "checked_in_at": null,
  "interval": "daily",
  "alert_type": "basic",
  "check_in_url": "https://nosnch.in/c2354d53d2",
  "created_at": "2014-03-28T22:07:44.902Z",
  "notes": "Postgres box at 123.213.231.132"
}

That should get you started! For more information, take a look at the reference below to learn how to modify, pause, and delete your snitches through the API.

Snitches Reference

You can show, create, edit, pause, and delete snitches through the API. See the sections below for details:

  1. Listing your Snitches
    1. Filtering Snitches by Tag
  2. Examining a Snitch
  3. Creating a Snitch
    1. Request Parameters
    2. Error Responses
  4. Editing a Snitch
    1. Adding one or more tags to a snitch
    2. Removing a tag from a snitch
    3. Changing tags on a snitch
  5. Pausing a Snitch
  6. Deleting a Snitch

Listing Your Snitches

The list action shows abbreviated information about all your snitches.

Try it in your browser!

$ curl -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches
[
  {
    "token": "c2354d53d2",
    "href": "/v1/snitches/c2354d53d2",
    "name": "Daily Backups",
    "tags": [
      "production",
      "critical"
    ],
    "status": "pending",
    "checked_in_at": "2014-01-01T12:00:00.000Z",
    "interval": "daily",
    "alert_type": "basic",
  },
  {
    "token": "c2354d53d2",
    "href": "/v1/snitches/c2354d53d2",
    "name": "Hourly Emails",
    "tags": [
    ],
    "status": "healthy",
    "checked_in_at": "2014-01-01T12:00:00.000Z",
    "interval": "hourly",
    "alert_type": "basic",
  }
]
Snitch Field Description
token The snitch's identifying token.
href The path to ask for if you want to know more about this snitch.
name The name of the snitch.
tags[] The list of keyword tags for this snitch.
status The status of the snitch. It could be:
"pending"The snitch is new and your job has not yet checked in.
"healthy"Your job has checked in since the beginning of the last period.
"failed"Your job has not checked in since the beginning of the last period. (At least one alert has been sent.)
"errored"Your job has reported that is has errored. (At least one alert has been sent.) Error Notices are only available on some plans.
"paused"The snitch has been paused and will not worry about your failing job until your job checks-in again after you fix it.
checked_in_at The last time your job checked in healthy, as an ISO 8601 datetime with millisecond precision. The timezone is always UTC. If your job has not checked in healthy yet, this will be null.
interval The size of the period window. If your job does not check-in during an entire period, you will be notified and the snitch status will show up as "failed". The interval can be "15_minute", "30_minute", "hourly", "daily", "weekly", or "monthly".
alert_type The type of alerts the snitch will use. basic will have a static deadline that it will expect to hear from it by, while smart will learn when your snitch checks in, moving the deadline closer so you can be alerted sooner.

If you have no snitches, nothing special happens. The returned array will simply be empty: [].

Order is not guaranteed to be consistent across subsequent requests.

Filtering Snitches by Tags

To filter your snitches by a set of tags, append a tags parameter with a comma-seperated list of tags to your /v1/snitches request. Snitches will be returned that match all tags listed.

https://api.deadmanssnitch.com/v1/snitches?tags=production,critical

Examining a Snitch

You can retreive more detailed information about an individual snitch.

$ curl -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches/c2354d53d2
{
  "token": "c2354d53d2",
  "href": "/v1/snitches/c2354d53d2",
  "name": "Daily Backups",
  "tags": [
    "production",
    "critical"
  ],
  "status": "pending",
  "checked_in_at": null,
  "interval": "daily",
  "alert_type": "basic",
  "check_in_url": "https://nosnch.in/c2354d53d2",
  "created_at": "2014-03-28T22:07:44.902Z",
  "notes": "Postgres box at 123.213.231.132"
}
Field Description
token The snitch's identifying token.
href The path to ask for if you want to know more about this snitch.
name The name of the snitch.
tags[] The list of keyword tags for this snitch.
status The status of the snitch. It could be:
"pending"The snitch is new and your job has not yet checked in.
"healthy"Your job has checked in since the beginning of the last period.
"failed"Your job has not checked in since the beginning of the last period. (At least one alert has been sent.)
"errored"Your job has reported that is has errored. (At least one alert has been sent.) Error Notices are only available on some plans.
"paused"The snitch has been paused and will not worry about your failing job until your job checks-in again after you fix it.
checked_in_at The last time your job checked in healthy, as an ISO 8601 datetime with millisecond precision. The timezone is always UTC. If your job has not checked in healthy yet, this will be null.
interval The size of the period window. If your job does not check-in during an entire period, you will be notified and the snitch status will show up as "failed". The interval can be "15_minute", "30_minute", "hourly", "daily", "weekly", or "monthly".
alert_type The type of alerts the snitch will use. basic will have a static deadline that it will expect to hear from it by, while smart will learn when your snitch checks in, moving the deadline closer so you can be alerted sooner.
check_in_url The url your job should hit to check-in.
created_at When the snitch was created, as an ISO 8601 datetime with millisecond precision. The timezone is always UTC.
notes Any user-supplied notes about this snitch.

If you request a snitch that doesn't exist, the response be HTTP status 404 and will also say:

{
  "type": "resource_not_found",
  "error": "The requested resource was not found."
}

Creating a Snitch

You can create a new snitch with the API. Construct a JSON representation of the snitch properties and send a POST request to /v1/snitches. Make sure you set a Content-Type: application/json header on the request.

Request parameters:

{
  "name": "Daily Backups",
  "interval": "daily",
  "alert_type": "basic",
  "notes": "Postgres box at 123.213.231.132",
  "tags": ["production", "critical"]
}
$ curl -X POST -d '{"name":"Daily Backups","interval":"daily","notes":"Postgres box at 123.213.231.132","tags": ["production", "critical"]}' -H "Content-Type: application/json" -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches
{
  "token": "c2354d53d2",
  "href": "/v1/snitches/c2354d53d2",
  "name": "Daily Backups",
  "tags": [
    "production",
    "critical"
  ],
  "status": "pending",
  "checked_in_at": null,
  "interval": "daily",
  "alert_type": "basic",
  "check_in_url": "https://nosnch.in/c2354d53d2",
  "created_at": "2014-04-02T15:54:54.784Z",
  "notes": "Postgres box at 123.213.231.132"
}

If the provided JSON is valid the snitch will be created. The response will have the information about the newly created snitch, in the same format as the GET action.

Request Parameters

Your request JSON can have the following parameters.

Field Description
name Required. The name of the snitch.
interval Required. The size of the period window. The interval must be "15_minute", "30_minute", "hourly", "daily", "weekly", or "monthly".
alert_type The type of alerts the snitch will use. Must be basic or smart. Default: basic
notes Any user-supplied notes about this snitch.
tags[] An array of tags for this snitch.

Error Responses

If the snitch wasn't created because your request JSON was malformed, the response HTTP status will be 422 (Unprocessable Entity), an error message will be set, and the type of the error will be "resource_invalid".

Here's an error from no attributes given:

$ curl -X POST -d '' -H "Content-Type: application/json" -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches
{
  "type": "resource_invalid",
  "error": "The requested resource attributes are not valid.",
  "validations": [
    {
      "attribute": "name",
      "message": "can't be blank"
    },
    {
      "attribute": "interval",
      "message": "can't be blank"
    }
  ]
}

Here's an error from an invalid interval:

$ curl -X POST -d '{"name":"Daily Backups","interval":"asdf"}' -H "Content-Type: application/json" -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches
{
  "type": "resource_invalid",
  "error": "The requested resource attributes are not valid.",
  "validations": [
    {
      "attribute": "interval",
      "message": "must be \"15_minute\", \"30_minute\", \"hourly\", \"daily\", \"weekly\", or \"monthly\""
    }
  ]
}

If you have the maximum number of snitches your plan allows, when you try to create another snitch you will recieve a response with HTTP status 402 (Payment Required). An error message will be set, and the type of the error will be plan_limit_reached.

$ curl -X POST -d '{"name":"Daily Backups","interval":"daily","notes":"Postgres box at 123.213.231.132"}' -H "Content-Type: application/json" -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches
{
  "type": "plan_limit_reached",
  "error": "We could not create your snitch because you are at your plan limit of 1 snitch! Delete an unused snitch, or head over to https://deadmanssnitch.com/account/plan to upgrade your plan."
}

Editing a Snitch

To edit a snitch, send a PATCH request to /v1/snitches/*token*.

Request parameters:

{
  "name": "Daily Backups",
  "interval": "daily",
  "alert_type": "smart",
  "notes": "Postgres box at 123.213.231.132",
  "tags": ["production", "critical"]
}
$ curl -i -X PATCH -d '{"name":"Daily Backups","interval":"daily","notes":"Postgres box at 123.213.231.132","tags": ["production", "critical"]}' -H "Content-Type: application/json" -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches/c2354d53d2
{
  "token": "c2354d53d2",
  "href": "/v1/snitches/c2354d53d2",
  "name": "Daily Backups",
  "tags": [
    "production",
    "critical"
  ],
  "status": "pending",
  "checked_in_at": null,
  "interval": "daily",
  "alert_type": "smart",
  "check_in_url": "https://nosnch.in/8514da189f",
  "created_at": "2014-04-02T15:54:54.784Z",
  "notes": "Postgres box at 123.213.231.132"
}

You may provide only the attributes you wish to change. Fields that do not appear in the request will not be touched.

Adding one or more tags to a snitch

To add one or more tags to a snitch, send a POST request to /v1/snitches/*token*/tags with an array of tags.

Example request parameters:

["production"]

Assuming a snitch already tagged "backup"...

$ curl -i -X POST -d '["production"]' -H "Content-Type: application/json" -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches/c2354d53d2/tags

...the response will be an array of all the snitch's tags.

[
  "backup",
  "production"
]

You can also add more than one tag...

$ curl -i -X POST -d '["production", "critical"]' -H "Content-Type: application/json" -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches/c2354d53d2/tags
[
  "backup",
  "production",
  "critical"
]

Removing a tag from a snitch

To remove a tag from a snitch, send a DELETE request to /v1/snitches/*c2354d53d2*/tags/*tag_name*.

Assuming a snitch with tags "production" and "critical"...

$ curl -i -X DELETE -H "Content-Type: application/json" -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches/c2354d53d2/tags/critical
[
  "production"
]

Changing tags on a snitch

To replace all the tags on a snitch, use the edit action: PATCH to /v1/snitches/*token*.

Request parameters:

{
  "tags": ["staging", "backup"]
}
$ curl -i -X PATCH -d '{"tags": ["staging", "backup"]}' -H "Content-Type: application/json" -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches/c2354d53d2
{
  "token": "c2354d53d2",
  "href": "/v1/snitches/c2354d53d2",
  "name": "Daily Backups",
  "tags": [
    "staging",
    "backup"
  ],
  "status": "pending",
  "checked_in_at": null,
  "interval": "daily",
  "alert_type": "smart",
  "check_in_url": "https://nosnch.in/8514da189f",
  "created_at": "2014-04-02T15:54:54.784Z",
  "notes": "Postgres box at 123.213.231.132"
}

Pass an empty array to remove all tags.

$ curl -i -X PATCH -d '{"tags": []}' -H "Content-Type: application/json" -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches/c2354d53d2
{
  "token": "c2354d53d2",
  "href": "/v1/snitches/c2354d53d2",
  "name": "Daily Backups",
  "tags": [
  ],
  "status": "pending",
  "checked_in_at": null,
  "interval": "daily",
  "alert_type": "smart",
  "check_in_url": "https://nosnch.in/8514da189f",
  "created_at": "2014-04-02T15:54:54.784Z",
  "notes": "Postgres box at 123.213.231.132"
}

Pausing a Snitch

To pause a snitch, send a POST request to /v1/snitches/*token*/pause.

$ curl -i -X POST -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches/c2354d53d2/pause

The response will be an empty, with an HTTP status of 204 (No content). To pause a snitch, it must either have a state of failed (hasn't checked in), errored, or healthy.

Deleting a Snitch

To delete a snitch, send a DELETE request to /v1/snitches/*token*.

$ curl -i -X DELETE -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches/c2354d53d2

The response will be empty, with an HTTP status of 204 (No content).

API Key Reference

All of the API actions (except the one that fetches your API key) require an API key for authentication. For every action, pass your key as the username in HTTP Basic Auth and leave the password blank.

Fetching Your Key

While your API key is available on your account page, you can also find your key through the API with your username and password over HTTP Basic Auth:

Try it in your browser

$ curl --user alice@example.com:password https://api.deadmanssnitch.com/v1/api_key
{
  "api_key": "_caeEiZXnEyEzXXYVh2NhQ"
}

Error Responses

If you provide no sign-in credentials or incorrect credentials, the response will have HTTP status 401 (Unauthorized). An error message will be set.

{
  "type": "sign_in_incorrect",
  "error": "Invalid email or password."
}

If you try to perform an action without a key or with an incorrect key, the response will have HTTP status 401 (Unauthorized) and an error message will be set.

{
  "type": "api_key_invalid",
  "error": "Access denied. Provide your API Key as the user for HTTP Basic Authentication."
}

Error Reference

HTTP response codes in the 200 range are all considered success. Error JSON responses all have an message in the error field. The error message may change in the future. If your program or script needs to know the error type, it should examine the type field. The type field is not expected to change.

Everything That Can Go Wrong

HTTP Status type error Probable Reason
400 Bad Request You probably have malformed JSON in your request body. This error does not have a response body—with curl you will need to use curl -i to see the "Bad Request" response status.
401 Unauthorized sign_in_incorrect Invalid email or password. The email or password provided over HTTP Basic Auth were either wrong or not present. This error only occurs when trying to fetch your API key.
401 Unauthorized api_key_invalid Access denied. Provide your API Key as the user for HTTP Basic Authentication. The API key provided in the HTTP Basic Auth username was invalid or not present.
402 Payment Required plan_limit_reached We could not create your snitch because you are at your plan limit! Delete an unused snitch, or head over to https://deadmanssnitch.com/account/plan to update your subscription. You need a bigger plan for your monitoring needs. Upgrade your plan or contact us with questions.
402 Payment Required account_on_hold Your account has been put on hold! Head over to https://deadmanssnitch.com/account/plan to update your subscription. Your account has been put on hold. This occurs after there have been too many failed payment attempts. Update your credit card or contact us with questions.
404 Not Found resource_not_found The requested resource was not found. You tried to access something that is not there or is not yours.
422 Unprocessable Entity resource_invalid The requested resource attributes are not valid. The requested values for the new snitch are either missing or incorrect. See the validations field of the error response for detailed information.
500 Internal Server Error Internal Server Error This should not happen—it means something unexpected went wrong inside the server. We've been notified. Try your request again. If you keep having problems, contact us and we will try to advise you on the issue.