Incidents API

List Incidents

GET /incidents

Returns a paginated list of incidents with enriched context.

Query Parameters

Parameter	Type	Description
workspaceId	number	Filter by workspace
projectId	number	Filter by project
checkId	number	Filter by check
state	string	ACTIVE or RESOLVED (case-insensitive; OPEN and MONITORING are aliases for ACTIVE)
page	number	Page number (default: 1)
limit	number	Items per page (default: 20)

Example

curl -H "Authorization: Bearer ionh_your_key" \
  "https://app.failsignal.com/api/incidents?workspaceId=1&state=ACTIVE"

Enriched Response

Each incident in the list includes additional context beyond the base entity:

Field	Type	Description
project	object	id and name of the parent project
check	object	id, name, and token of the check
dependency	object	id and name (only for DEPENDENCY_DOWN incidents)
acknowledgedByUser	object	id and email (if acknowledged)
lastSignalAt	string	ISO timestamp of the latest signal
lastSignalType	string	SUCCESS, SUSPECT, FAIL, or DEPLOYMENT
lastSignalSource	string	Where the signal came from
lastSuccessAt	string	ISO timestamp of the last successful signal
durationSinceSuccessMs	number	Milliseconds since last success

Get Incident

GET /incidents/:id

Returns a single incident with the same enriched fields as the list endpoint.

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

Acknowledge Incident

POST /incidents/:id/acknowledge

Marks an incident as acknowledged by the current user. Acknowledgment signals that someone is actively investigating.

curl -X POST https://app.failsignal.com/api/incidents/456/acknowledge \
  -H "Authorization: Bearer ionh_your_key"

The response includes:

• acknowledgedBy — the user ID
• acknowledgedAt — the timestamp

Acknowledging an already-acknowledged incident returns the same result (idempotent). Acknowledging a resolved incident returns a 409 Conflict.

Incident Events (Timeline)

GET /incident-events/:incidentId

Returns the event timeline for an incident — an immutable audit log of everything that happened.

curl -H "Authorization: Bearer ionh_your_key" \
  https://app.failsignal.com/api/incident-events/456

Event Types

Type	When it's created
OPENED	Incident was created
ACKNOWLEDGED	A user acknowledged the incident
ALERT_SENT	A notification was dispatched (email or Slack)
RESOLVED	Incident was resolved (automatically or manually)

Each event includes:

• type — the event type
• message — human-readable description
• occurredAt — ISO timestamp

Incident Notes

Notes let you document investigation findings, root cause analysis, and remediation steps directly on an incident.

List Notes

GET /incident-notes/:incidentId

curl -H "Authorization: Bearer ionh_your_key" \
  https://app.failsignal.com/api/incident-notes/456

Create Note

POST /incident-notes/:incidentId

curl -X POST https://app.failsignal.com/api/incident-notes/456 \
  -H "Authorization: Bearer ionh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"body": "Root cause identified: database connection pool exhausted after deploy."}'

Update Note

PATCH /incident-notes/:incidentId/:noteId

Only the note's author can update it.

curl -X PATCH https://app.failsignal.com/api/incident-notes/456/789 \
  -H "Authorization: Bearer ionh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"body": "Updated root cause: connection pool exhausted due to missing pool size config."}'

Delete Note

DELETE /incident-notes/:incidentId/:noteId

Only the note's author can delete it. Notes are soft-deleted (retained for audit purposes).

Incident Fields Reference

Field	Type	Description
id	number	Incident ID
checkId	number	The check that triggered this incident
title	string	Human-readable title
summary	string	Optional detailed description
state	string	ACTIVE or RESOLVED
reason	string	SERVICE_DOWN or DEPENDENCY_DOWN
severity	string	CRITICAL (service down) or WARNING (dependency down)
startedAt	string	When the incident was created
resolvedAt	string	When the incident was resolved (null if active)
recoveredAt	string	When the service actually recovered
acknowledgedBy	number	User ID who acknowledged (null if not acknowledged)
acknowledgedAt	string	When it was acknowledged
dependencyId	number	The dependency that caused the impact (for DEPENDENCY_DOWN)
dependencyName	string	Name of the impacted dependency
publicId	string	ULID for public-facing incident references