Docs
API

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"
    ],
    "notes": "Backups run on Marvin",
    "status": "pending",
    "checked_in_at": "2014-01-01T12:00:00.000Z",
    "created_at": "2013-12-30T06:30:00.000Z",
    "interval": "daily",
    "alert_type": "basic",
    "alert_email": []
  },
  {
    "token": "c2354d53d2",
    "href": "/v1/snitches/c2354d53d2",
    "name": "Hourly Emails",
    "tags": [],
    "status": "healthy",
    "checked_in_at": "2014-01-01T12:00:00.000Z",
    "created_at": "2013-12-30T14:12:01.123Z",
    "interval": "hourly",
    "alert_type": "basic",
    "alert_email": [ "alerts@example.com" ]
  }
]

With your API key from the last action, you can list your snitches in your browser: http://api.localhost:3000/v1/snitches.

You can also 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",
  "alert_email": [],
  "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 Snitches to learn how to modify, pause, and delete your snitches through the API.

Snitches

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

Listing Snitches
1. Filtering by Tag
Examining a Snitch
Creating a Snitch
1. Request Parameters
2. Error Responses
Updating a Snitch
Pausing a Snitch
Unpausing a Snitch
Deleting a Snitch

Listing Snitches

The list action returns detailed information about all of the Snitches on the Case. Order is not guaranteed to be consistent across subsequent requests.

curl -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches[
  {
    "token": "c2354d53d2",
    "href": "/v1/snitches/c2354d53d2",
    "name": "Daily Backups",
    "tags": [
      "production",
      "critical"
    ],
    "notes": "Backups run on Marvin",
    "status": "pending",
    "checked_in_at": "2014-01-01T12:00:00.000Z",
    "created_at": "2013-12-30T06:30:00.000Z",
    "interval": "daily",
    "alert_type": "basic",
    "alert_email": [],
  },
  {
    "token": "c2354d53d2",
    "href": "/v1/snitches/c2354d53d2",
    "name": "Hourly Emails",
    "tags": [],
    "status": "healthy",
    "checked_in_at": "2014-01-01T12:00:00.000Z",
    "created_at": "2013-12-30T14:12:01.123Z",
    "interval": "hourly",
    "alert_type": "basic",
    "alert_email": [ "alerts@example.com" ]
  }
]

Field Type Description

token string The snitch's identifying token.

href string API URL to retrieve data about this specific Snitch.

name string The name of the snitch.

tags array The list of keyword tags for this snitch.

status

string

The status of the snitch. Will be one of:

`"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.

notes string Any user-supplied notes about this snitch.

checked_in_at string null The last time your job checked in healthy, as an ISO 8601 datetime with millisecond precision. The timezone is always UTC. checked_in_at will be null when the Snitch has not checked in yet.

check_in_url string The url your job should hit to check-in.

interval string How often the task is expected to run or time between heartbeats. If a Snitch does not check-in during an entire interval then you will be notified and the Snitch's status will show up as "failed".

See interval under request parameters for the list of expected values.

alert_type string 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.

alert_email array Override list of emails to be notified for Snitch changes. By default, all members of the team will receive email alerts for the Snitch.

created_at string When the snitch was created, as an ISO 8601 datetime with millisecond precision. The timezone is always UTC.

Filtering by Tag(s)

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

curl -u _caeEiZXnEyEzXXYVh2NhQ:
https://api.deadmanssnitch.com/v1/snitches?tags=production,critical

If no snitches match the filter (or there are no snitches on the Case), we'll respond with an empty array ([]).

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",
  "alert_email": [],
  "check_in_url": "https://nosnch.in/c2354d53d2",
  "created_at": "2014-03-28T22:07:44.902Z",
  "notes": "Postgres box at 123.213.231.132"
}

Field Type Description

token string The snitch's identifying token.

href string API URL to retrieve data about this specific Snitch.

name string The name of the snitch.

tags array The list of keyword tags for this snitch.

status

string

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.

notes string Any user-supplied notes about this snitch.

checked_in_at string null 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 yet, this will be null.

check_in_url string The url your job should hit to check-in.

alert_email array Override list of emails to be notified for Snitch changes. By default, all members of the team will receive email alerts for the Snitch.

created_at string When the snitch was created, as an ISO 8601 datetime with millisecond precision. The timezone is always UTC.

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

curl -u _caeEiZXnEyEzXXYVh2NhQ: https://api.deadmanssnitch.com/v1/snitches/c2354d53d2{
  "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.

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

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 Type Description

name string Required. The name of the snitch.

interval

string

Required. How often the task runs or heartbeat is sent to Dead Man's Snitch.

Must be one of:

`1_minute`	Every minute (Basic only)
`2_minute`	Every two minutes (Basic only)
`3_minute`	Every three minutes (Basic only)
`5_minute`	Every five minutes (Basic only)
`10_minute`	Every ten minutes (Basic only)
`15_minute`	Every fifteen minute (Basic only)
`30_minute`	Every thirty minute (Basic only)
`hourly`	Every hour
`2_hour`	Every two hours
`3_hour`	Every three hours
`4_hour`	Every four hours
`6_hour`	Every six hours
`8_hour`	Every eight hours
`12_hour`	Every twelve hours
`daily`	Once per day
`weekly`	Once per week (Monday to Monday)
`monthly`	Once per month

alert_type string The type of alerts the snitch will use. Must be basic or smart. Default: basic

alert_email

array string null

Optional. Override list of emails to be notified when the Snitch goes missing, errors, or starts reporting. When set, alerts will only be sent to this list of email addresses. By default all members of the team will receive alerts via email.

Value can be either an array of email addresses or a comma separated list of addresses. Use either null or [] to disable the override.

notes string null Any user-supplied notes about this snitch.

tags array null 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]

$ 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",
  "alert_email": [],
  "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.

Assuming a snitch already tagged "backup", the response will be an array of all the snitch's tags.

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

You can also add more than one tag at a time.

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]

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",
  "alert_email": [],
  "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",
  "alert_email": [],
  "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

Pausing a Snitch will mute any alerts from the Snitch until the next time it checks-in with Dead Man's Snitch or a specific time or condition is met. It is safe to pause a Snitch that is already paused.

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 empty, with an HTTP status of 204 No Content. A Snitch can only be paused if is not in the pending state (i.e. has checked-in at least once).

Request Parameters

Field Type Description

until

string

Optional

Provide a timestamp or condition when the Snitch will be unpaused. By default (when not provided) a Snitch will be automatically unpaused the next time it checks-in healthy (i.e. does not include an error code) to Dead Man's Snitch.

Must be one of:

`healthy`	Unpause on next healthy check-in (default)
`unpaused`	Pause until manually unpaused
`[timestamp]`	ISO 8601 formatted timestamp in the future

Pause Until a Time

curl -X POST \
   -d '{"until":"2024-11-21T09:44:56.229Z"}' \
   -H "Content-Type: application/json" \
   -u _caeEiZXnEyEzXXYVh2NhQ: \
   https://api.deadmanssnitch.com/v1/snitches/c2354d53d2/pause

Errors

HTTP 422 Unprocessable Entity will be returned when the until parameter is invalid (i.e. is not a valid time, condition, or is in the past). Details on the error response is outlined in the error responses section below.

Unpausing a Snitch

Unpausing a Snitch will re-enable alerting for missed task runs or errors for a Snitch that has had alerting paused. It is safe to call unpause for a Snitch that has not been paused.

To unpause a Snitch, send a POST request to /v1/snitches/[token]/unpause

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

The response will be 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 Keys

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.

API Key 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 Responses

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.
503 Service Unavailable	service_unavailable	Dead Man's Snitch is undergoing maintenance	We've temporarily taken part of the service offline for a maintenance we can't perform live. You can check the status page for updates.