Checks API

List Checks

GET /checks

Returns a paginated list of checks in the workspace.

Query Parameters

Parameter	Type	Description
workspaceId	number	Filter by workspace
projectId	number	Filter by project
checkMode	string	Filter by mode: INBOUND or OUTBOUND
page	number	Page number (default: 1)
limit	number	Items per page (default: 10)

Example

curl -H "Authorization: Bearer ionh_your_key" \
  "https://app.failsignal.com/api/checks?workspaceId=1&checkMode=INBOUND"

Get Check

GET /checks/:id

Returns a single check with its configuration. For outbound checks, includes the outbound config and latest probe state.

curl -H "Authorization: Bearer ionh_your_key" \
  https://app.failsignal.com/api/checks/123

Get Check by Token

GET /checks/token/:token

Returns a check by its ping token, including recent signals and dependencies.

Create Check

POST /checks

Inbound Check (Heartbeat)

curl -X POST https://app.failsignal.com/api/checks \
  -H "Authorization: Bearer ionh_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly Backup",
    "projectId": 1,
    "intervalSeconds": 3600,
    "graceSeconds": 30,
    "checkMode": "INBOUND"
  }'

Outbound Check (HTTP Probe)

curl -X POST https://app.failsignal.com/api/checks \
  -H "Authorization: Bearer ionh_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Health",
    "projectId": 1,
    "intervalSeconds": 300,
    "graceSeconds": 15,
    "checkMode": "OUTBOUND",
    "url": "https://api.example.com/health",
    "checkType": "HTTP",
    "method": "GET",
    "expectedStatusMin": 200,
    "expectedStatusMax": 299,
    "timeoutMs": 5000,
    "failAfterConsecutive": 3,
    "resolveAfterConsecutiveSuccess": 2,
    "regions": ["us-east-1", "eu-west-1"]
  }'

Request Body

Core Fields

Field	Type	Required	Description
name	string	Yes	Check name (1–255 characters)
projectId	number	Yes*	Project to associate with
dependencyId	number	Yes*	Dependency to associate with (mutually exclusive with projectId)
intervalSeconds	number	Yes	Probe/ping interval (60–3,600 seconds)
graceSeconds	number	Yes	Grace period before alerting (5–60 seconds)
checkMode	string	No	INBOUND (default) or OUTBOUND
muteNotifications	boolean	No	Suppress alerts for this check (default: false)
dependencyIds	number[]	No	Check-based dependency IDs

* Exactly one of projectId or dependencyId is required.

Outbound-Specific Fields

Required when checkMode is OUTBOUND:

Field	Type	Default	Description
url	string	—	Target URL (must be http:// or https://, max 2,048 chars)
checkType	string	HTTP	HTTP, TCP, DNS, or ICMP
method	string	GET	GET, HEAD, POST, PUT, or PATCH
customHeaders	object	—	Custom HTTP headers (max 10)
timeoutMs	number	8000	Request timeout (1,000–15,000 ms)
expectedStatusMin	number	200	Minimum acceptable status code (100–599)
expectedStatusMax	number	399	Maximum acceptable status code (100–599)
followRedirects	boolean	true	Follow HTTP redirects
maxRedirects	number	3	Maximum redirect hops (0–3)
blockHttpDowngrade	boolean	true	Block HTTPS to HTTP redirects
failAfterConsecutive	number	3	Consecutive failures before DOWN (1–10)
resolveAfterConsecutiveSuccess	number	2	Consecutive successes before OK (1–10)
latencyWarnMs	number	—	Latency alert threshold in ms
sslExpiryWarnDays	number	14	SSL expiry warning threshold (1–365 days)
regions	string[]	—	Probe regions: us-east-1, eu-west-1, ap-southeast-1

Response

Returns the created check with a generated token for heartbeat pings.

Constraints

• Inbound checks: minimum interval is 300 seconds (5 minutes).
• Outbound checks cannot be associated with dependencies (must use projectId).
• Check count limits are enforced per workspace based on your plan.
• Outbound check limits are enforced separately.

Update Check

PATCH /checks/:id

Accepts the same fields as creation. Only include fields you want to change.

curl -X PATCH https://app.failsignal.com/api/checks/123 \
  -H "Authorization: Bearer ionh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"graceSeconds": 45}'

Delete Check

DELETE /checks/:id

Soft-deletes the check. Associated signals are cleaned up and open incidents are resolved.

curl -X DELETE https://app.failsignal.com/api/checks/123 \
  -H "Authorization: Bearer ionh_your_key"

Pause Check

PUT /checks/:id/pause

Pauses the check. Paused checks don't trigger alerts or create incidents for missed signals.

curl -X PUT https://app.failsignal.com/api/checks/123/pause \
  -H "Authorization: Bearer ionh_your_key"

Resume Check

PUT /checks/:id/resume

Resumes a paused check. Monitoring begins again from the next expected interval.

curl -X PUT https://app.failsignal.com/api/checks/123/resume \
  -H "Authorization: Bearer ionh_your_key"

Transfer Check

PATCH /checks/:id/transfer

Moves a check to a different project within the same workspace.

curl -X PATCH https://app.failsignal.com/api/checks/123/transfer \
  -H "Authorization: Bearer ionh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"projectId": 5}'

Check Badge

GET /checks/:id/badge

Returns a shields.io-style status badge. No authentication required.

Redirects to a colored badge based on the check's current status (green for OK, red for DOWN).

![Status](https://app.failsignal.com/api/checks/123/badge)

Outbound Check Endpoints

Get Outbound Config

GET /checks/:id/outbound

Returns the outbound configuration and latest probe state.

Update Outbound Config

PATCH /checks/:id/outbound

Updates the outbound check configuration (URL, headers, timeout, thresholds, regions).

Get Run History

GET /checks/:id/runs

Returns paginated probe run history.

Parameter	Type	Description
page	number	Page number
limit	number	Items per page
startDate	ISO string	Filter runs after this date
endDate	ISO string	Filter runs before this date

Get Outbound Stats

GET /checks/:id/outbound-stats

Returns aggregated statistics (uptime percentage, average latency, P95 latency) for a time window (default: 24 hours).

Get Outbound Timeline

GET /checks/:id/outbound-timeline

Returns bucketed probe results over time (default: 5-minute buckets over 24 hours).