Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt

Use this file to discover all available pages before exploring further.

The forensic model records every decision the detection engine makes as an immutable database row. Use it to answer “why did this incident fire?”, “what policy was in effect?”, and “which check caused the transition?” — without re-running the data.

​
What gets recorded

Three row types are written for every check that flows through detection:
  • Rule evaluations — one row per rule evaluated against a check result. Captures rule type (consecutive_failures, response_time, …), region, inputs, outputMatched flag, and the policy snapshot hash.
  • State transitions — one row per status edge walked (WATCHING → TRIGGERED, TRIGGERED → CONFIRMED, CONFIRMED → RESOLVED, …). Carries triggeringEvaluationIds, checkId, policySnapshotHashHex, and engineVersion. The reason field distinguishes detection-engine causes (trigger, confirm, resolve, auto_clear, reopen) from user-driven actions (manually_resolved).
  • Policy snapshots — content-addressed by SHA-256 of the policy JSON. The exact policy that was active at evaluation time, even if the monitor has been edited since.
All rows are tagged with organizationId and the originating checkId, so you can thread a single check execution across both writes.

​
Endpoints

All endpoints are read-only and live under /api/v1/forensics/:
EndpointPurpose
GET /forensics/incidents/{id}/timelineFull timeline for an incident: transitions + triggering evaluations + active policy snapshot
GET /forensics/traces/{checkId}Everything recorded for a single check execution
GET /forensics/policy-snapshots/{hashHex}Fetch a policy snapshot by its SHA-256 hash
GET /forensics/monitors/{id}/rule-evaluationsPaginated list of rule evaluations for a monitor (filters: ruleType, region, onlyMatched, from, to)
GET /forensics/monitors/{id}/transitionsPaginated list of state transitions for a monitor (filters: from, to)

​
CLI

devhelm forensics timeline <incident-id>
devhelm forensics trace <check-id>
devhelm forensics snapshot <hash-hex>
devhelm forensics evaluations --monitor-id <uuid> --only-matched
devhelm forensics transitions --monitor-id <uuid> --from 2026-04-01T00:00:00Z
Every command supports --output json|yaml|table and the standard auth flags.

​
SDKs

import {createClient} from '@devhelm/sdk'

const client = createClient({apiToken: process.env.DEVHELM_API_TOKEN!})

const timeline = await client.forensics.incidentTimeline(incidentId)
const trace = await client.forensics.checkTrace(checkId)
const snapshot = await client.forensics.policySnapshot(hashHex)

const {data: evals} = await client.forensics.monitorRuleEvaluations(monitorId, {
  onlyMatched: true,
  ruleType: 'consecutive_failures',
})

​
MCP tools

The DevHelm MCP server exposes the same read path to AI agents:
  • get_incident_timeline(incident_id) — replay why an incident fired
  • get_check_trace(check_id) — inspect a single check execution
  • get_policy_snapshot(hash_hex) — fetch the exact policy active at a past moment
  • list_monitor_rule_evaluations(monitor_id, ...) — audit rule firings
  • list_monitor_transitions(monitor_id, ...) — reconstruct monitor lifecycle
See the MCP tools reference for full signatures.

​
Use cases

  • Incident replay: a customer asks “why did we get paged?” — the timeline endpoint returns the check, policy, and rules involved, no log scraping needed.
  • Policy change review: before editing a trigger rule, fetch the snapshot hash that fired the last incident and diff it against the new policy.
  • False-positive audit: list rule-evaluations?onlyMatched=true for a monitor over the last 7 days to spot noisy rules.
  • Cross-region analysis: filter rule-evaluations?region=us-east to see how one region contributed to confirmation.

​
Retention

Rows live in TimescaleDB hypertables and are retained per standard time-series retention policy (currently 90 days). Policy snapshots are kept indefinitely — they’re small and content-addressed, and deleting them would orphan references from retained evaluations/transitions.

​
Next steps

Incident Timeline

Human-facing view of an incident’s lifecycle — status changes, updates, and notifications.

Incident Policies

Configure the trigger and recovery rules that forensics record.

MCP Tools Reference

Let an AI agent query the forensic model directly.

API Reference

Full schema for every forensic endpoint.