API Reference

Programmatically manage your dead man switches, automate check-ins, and integrate key holder workflows into your own applications.

Introduction

The Failsafe.app REST API lets you read and write switches and key holders using standard HTTP methods. All request and response bodies use JSON. The API is versioned — the current version is v1.

API access requires a paid plan that includes API support. You can create and manage API keys from Settings → API Keys.

Authentication

All requests must include a secret API key as a Bearer token in the Authorization header. Never expose your secret key in client-side code or public repositories.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

HTTPS required. All API requests must be made over HTTPS. HTTP requests will be rejected with 403 Forbidden.

API Key Scopes

When creating an API key you define its scope — the exact paths and methods the key is permitted to call. Scope entries use the format METHOD:/path and support wildcards and path parameters:

GET:/v1/switches
POST:/v1/switches/:uuid/checkin
*:*

A request that doesn't match any scope entry is rejected with 403 Forbidden.

CIDR Restrictions

Optionally restrict an API key to specific IP ranges by adding CIDR blocks (e.g. 203.0.113.0/24). If any CIDR blocks are configured, requests from IPs outside those ranges are rejected with 403 Forbidden.

Base URL

https://api.failsafe.app/v1/

Rate Limiting

The API uses a leaky bucket algorithm. Each key has a configurable request-per-minute limit (default: 60). When the limit is exceeded the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

Errors

All responses include an errors array. On success it is empty. On failure it contains one or more error objects:

{
  "errors": [
    {
      "message": "Switch not found.",
      "type": "invalid_request_error"
    }
  ]
}

type	Meaning
auth_error	Missing or invalid API key
security_error	HTTPS required, IP blocked, or scope denied
invalid_request_error	Missing parameter, wrong type, resource not found
rate_limit_error	Too many requests
api_error	Unexpected server-side error

Ping

GET /v1/ping

Verify connectivity and confirm your API key is valid.

curl https://api.failsafe.app/v1/ping \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "timestamp": "Sat, 01 Mar 2026 12:00:00 GMT",
  "errors": []
}

Switches

A switch is the core object. There are two types:

type	Value	Description
TYPE_CHECK_IN	1	Owner must check in periodically. Missing the deadline triggers delivery.
TYPE_KEY_HOLDER	2	A quorum of trusted key holders must activate the switch within a time window.

status	Value	Description
STATUS_ACTIVE	1	Operational — accepting check-ins or activations.
STATUS_TRIGGERED	2	Switch has been triggered — delivery is in progress.

GET /v1/switches

Returns all switches for the authenticated user.

curl https://api.failsafe.app/v1/switches \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "data": [
    {
      "uuid": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "Personal Documents",
      "type": 1,
      "status": 1,
      "check_in_interval": 2592000,
      "checked_in_last_at": "2026-02-28T14:32:00.000000Z",
      "created_at": "2026-01-15T10:00:00.000000Z",
      "updated_at": "2026-02-28T14:32:00.000000Z"
    }
  ],
  "errors": []
}

GET /v1/switches/:uuid

Returns a single switch by UUID.

curl https://api.failsafe.app/v1/switches/01234567-89ab-cdef-0123-456789abcdef \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "data": {
    "uuid": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Personal Documents",
    "type": 1,
    "status": 1,
    "check_in_interval": 2592000,
    "checked_in_last_at": "2026-02-28T14:32:00.000000Z",
    "created_at": "2026-01-15T10:00:00.000000Z",
    "updated_at": "2026-02-28T14:32:00.000000Z"
  },
  "errors": []
}

POST /v1/switches

Creates a new switch. Plan limits apply.

Parameter	Type		Description
name	string	required	Display name for the switch.
type	integer	required	1 = CHECK_IN, 2 = KEY_HOLDER
check_in_interval	integer	optional	Seconds between required check-ins. Required when type=1.
key_holder_interval	integer	optional	Window in seconds for quorum activation. Required when type=2.
key_holders_required	integer	optional	Number of key holder activations needed to trigger. Required when type=2.

curl -X POST https://api.failsafe.app/v1/switches \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Crypto Keys",
    "type": 1,
    "check_in_interval": 2592000
  }'

{
  "data": {
    "uuid": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "Crypto Keys",
    "type": 1,
    "status": 1,
    "check_in_interval": 2592000,
    "checked_in_last_at": null,
    "created_at": "2026-03-01T12:00:00.000000Z",
    "updated_at": "2026-03-01T12:00:00.000000Z"
  },
  "errors": []
}

PUT /v1/switches/:uuid

Updates fields on an existing switch. Only the fields you supply are changed.

Parameter	Type		Description
name	string	optional	New display name.
status	integer	optional	1 = active, 2 = triggered.
check_in_interval	integer	optional	Seconds between check-ins.
key_holder_interval	integer	optional	Quorum window in seconds.
key_holders_required	integer	optional	Number of activations needed.

curl -X PUT https://api.failsafe.app/v1/switches/01234567-89ab-cdef-0123-456789abcdef \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "check_in_interval": 604800}'

{
  "data": { "uuid": "01234567-...", "name": "Updated Name", ... },
  "errors": []
}

DELETE /v1/switches/:uuid

Permanently deletes a switch. This cannot be undone.

curl -X DELETE https://api.failsafe.app/v1/switches/01234567-89ab-cdef-0123-456789abcdef \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "deleted": true,
  "errors": []
}

POST /v1/switches/:uuid/checkin

Records a check-in for a TYPE_CHECK_IN switch, resetting the heartbeat timer. This is the endpoint you'll call from a cron job, monitoring agent, or any automated process to prove you're alive.

Automate this. Call this endpoint on a schedule that's shorter than your switch's check_in_interval. If the endpoint stops being called the switch will trigger and delivery will begin.

curl -X POST https://api.failsafe.app/v1/switches/01234567-89ab-cdef-0123-456789abcdef/checkin \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "data": {
    "uuid": "01234567-89ab-cdef-0123-456789abcdef",
    "status": 1,
    "checked_in_last_at": "2026-03-01T13:45:00.000000Z"
  },
  "errors": []
}

POST /v1/switches/:uuid/activate

Records an activation by a key holder on a TYPE_KEY_HOLDER switch. Once the required number of key holders have activated within the configured window, the switch is triggered and triggered: true is returned.

Parameter	Type		Description
key_holder_uuid	string	required	UUID of the key holder activating the switch.

curl -X POST https://api.failsafe.app/v1/switches/01234567-89ab-cdef-0123-456789abcdef/activate \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"key_holder_uuid": "aabbccdd-eeff-0011-2233-445566778899"}'

{
  "triggered": false,
  "errors": []
}

Key Holders

A key holder is a trusted person who can be assigned to one or more switches. Key holders must verify their email address before they can be linked to a switch.

GET /v1/key-holders

Returns all key holders for the authenticated user.

curl https://api.failsafe.app/v1/key-holders \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "data": [
    {
      "uuid": "aabbccdd-eeff-0011-2233-445566778899",
      "name": "Jane Smith",
      "email_address": "jane@example.com",
      "status": 2,
      "created_at": "2026-01-20T10:00:00.000000Z",
      "updated_at": "2026-01-20T10:00:00.000000Z"
    }
  ],
  "errors": []
}

GET /v1/key-holders/:uuid

Returns a single key holder by UUID.

curl https://api.failsafe.app/v1/key-holders/aabbccdd-eeff-0011-2233-445566778899 \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "data": {
    "uuid": "aabbccdd-eeff-0011-2233-445566778899",
    "name": "Jane Smith",
    "email_address": "jane@example.com",
    "status": 2,
    "created_at": "2026-01-20T10:00:00.000000Z",
    "updated_at": "2026-01-20T10:00:00.000000Z"
  },
  "errors": []
}

POST /v1/key-holders

Registers a new key holder and sends them a verification email. The key holder must click the link in the email before they can be assigned to a switch.

Parameter	Type		Description
name	string	required	Key holder's display name.
email_address	string	required	Key holder's email address. Must be unique per account.
pin	string	optional	Optional PIN for identity verification during delivery.

curl -X POST https://api.failsafe.app/v1/key-holders \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email_address": "jane@example.com"
  }'

{
  "data": {
    "uuid": "aabbccdd-eeff-0011-2233-445566778899",
    "name": "Jane Smith",
    "email_address": "jane@example.com",
    "status": 1,
    "created_at": "2026-03-01T14:00:00.000000Z",
    "updated_at": "2026-03-01T14:00:00.000000Z"
  },
  "errors": []
}

DELETE /v1/key-holders/:uuid

Permanently deletes a key holder and removes them from any switch assignments.

curl -X DELETE https://api.failsafe.app/v1/key-holders/aabbccdd-eeff-0011-2233-445566778899 \
  -H "Authorization: Bearer sk_live_xxxx"

{
  "deleted": true,
  "errors": []
}