Dead Man's Snitch

API Reference

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.

Getting Started

You access the API using an API key. You can manage your case's API keys on your case's API Keys page. Create a new one and copy the token to use in your API requests.

Once you have an API Key, use it as the username for accessing all API actions. 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 Snitches
    1. Filtering by Tag
  2. Examining a Snitch
  3. Creating a Snitch
    1. Request Parameters
    2. Error Responses
  4. Updating a Snitch
    1. Adding tag(s)
    2. Removing tag(s)
    3. Changing tags on a snitch
  5. Pausing a Snitch
  6. Deleting a Snitch

Listing Snitches

The list action shows abbreviated information about all your 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",
  }
]
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 by Tag(s)

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/ to upgrade your plan."
}

Updating a Snitch

To update 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 require an API key for authentication. For every action, pass your key as the username in HTTP Basic Auth and leave the password blank.

Obtaining an API Key

You can manage your case's API keys on your case's API Keys page. Create a new one and copy the token to use in your API requests. You can create a unique key for each place that will be accessing the snitches for that case.

Error Responses

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 a 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.

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 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/ 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 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.
429 Rate Limited rate_limited You have made too many requests too quickly. Your API key has been used to make a large number of requests in a short period and has been temporarily blocked.
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.