API reference

The Parachute REST API lets you ingest alerts, manage runbooks, query incidents, retrieve evidence packages, and configure webhooks programmatically.

Base URL: https://api.withparachute.org/v1. All requests must use HTTPS. HTTP requests are rejected with a 301 redirect.

Authentication

All API requests must include a Bearer token in the Authorization header. Tokens are workspace-scoped and can be created in Workspace settings > API tokens.

Authorization header 
Authorization: Bearer prc_live_xxxxxxxxxxxxxxxxxxxxxxxx

Token format: prc_live_ prefix for production tokens, prc_test_ for tokens created in test mode. Test mode tokens only affect the sandbox intake endpoint.

Rate limits

Rate limits apply per workspace, not per token. Exceeding the limit returns 429 Too Many Requests with a Retry-After header (seconds).

Rate limit table 
Developer plan    :  60 req/min  (alert intake: 20 req/min)
Starter plan      : 200 req/min  (alert intake: 100 req/min)
Professional plan : 600 req/min  (alert intake: 300 req/min)
Enterprise        :  Custom limit on request

Alerts

Use the Alerts endpoint to ingest raw alert payloads into Parachute. Alerts are matched against runbook trigger conditions and execute any matching runbooks.

POST /alerts

Ingest an alert into the workspace. Returns the alert ID and matched runbook IDs synchronously; runbook execution is asynchronous.

POST /alerts: request 
POST /v1/alerts HTTP/1.1
Host: api.withparachute.org
Authorization: Bearer prc_live_xxx
Content-Type: application/json

{
  "source": "datadog",
  "severity": "critical",
  "title": "EC2 brute force detected on i-0abc123456",
  "host_id": "i-0abc123456",
  "tags": ["brute-force", "ec2", "prod"],
  "raw_payload": { ... }
}
POST /alerts: response 201 
{
  "alert_id": "alrt_01j8xxx",
  "matched_runbooks": ["rb_ec2_brute_force"],
  "executions_started": 1
}

GET /alerts

List alerts ingested into the workspace. Accepts query parameters: since (ISO 8601 timestamp), severity, source, limit (default 50, max 500), cursor (pagination cursor from previous response).

Runbooks

Manage runbook definitions via the API. Useful for GitOps workflows where runbook YAML is version-controlled and synced programmatically.

GET /runbooks

List all runbooks in the workspace. Returns ID, name, status (active/inactive/draft), version, and last-modified timestamp.

PUT /runbooks/{id}

Update a runbook definition. Body is the full YAML document as a JSON string under "yaml". Returns the updated runbook object with the new version number.

POST /runbooks/{id}/activate

Set a runbook's status to active. Runbooks must be in valid/passing dry-run state to be activated via API.

Incidents

Incidents are created automatically when a runbook executes. Use the Incidents endpoint to query status, retrieve execution timelines, and update resolution state.

GET /incidents

List incidents. Accepts: status (open/resolved/suppressed), runbook_id, since, limit, cursor.

GET /incidents/{id}

Retrieve a single incident with full execution timeline, step results, and evidence manifest.

GET /incidents/{id}: response 
{
  "incident_id": "inc_01j8xxx",
  "runbook_id": "rb_ec2_brute_force",
  "alert_id": "alrt_01j8xxx",
  "status": "resolved",
  "started_at": "2026-06-01T03:14:22Z",
  "resolved_at": "2026-06-01T03:14:41Z",
  "duration_ms": 19000,
  "steps": [
    { "id": "isolate", "status": "success", "duration_ms": 4200 },
    { "id": "collect",  "status": "success", "duration_ms": 8100 },
    { "id": "timeline", "status": "success", "duration_ms": 5700 },
    { "id": "notify",   "status": "success", "duration_ms": 1000 }
  ],
  "evidence_ids": ["evd_01j8xxx"]
}

PATCH /incidents/{id}

Update incident status. Accepted body: {"status": "resolved"} or {"status": "suppressed", "reason": "..."}.

Evidence

Evidence packages are created by pull_logs and capture_process_list runbook actions. They contain raw log files, process snapshots, and the AI-generated timeline.

GET /evidence/{id}

Retrieve evidence package metadata and a pre-signed download URL valid for 15 minutes. The evidence archive is a .tar.gz containing all collected artifacts.

Retention: Evidence is permanently deleted when the workspace retention window expires. Download before the expiry if you need long-term storage.

Webhooks

Parachute can push events to your own endpoint when incidents open, steps complete, or evidence is collected.

POST /webhooks

Register a webhook endpoint. Specify the target URL and the event types to subscribe to.

POST /webhooks: request 
{
  "url": "https://your-endpoint.example.com/parachute",
  "events": ["incident.opened", "incident.resolved", "evidence.collected"],
  "secret": "your-hmac-secret"
}

Webhook event payload

All webhook deliveries include an X-Parachute-Signature-256 header. Verify it against HMAC-SHA256(secret, raw_body) before processing.

Webhook event types

  • incident.opened - A runbook execution began
  • incident.resolved - An incident was marked resolved
  • incident.step_completed - A single runbook step completed
  • evidence.collected - A new evidence package was created
  • alert.no_match - An alert was ingested but no runbook matched

Errors

All errors return a JSON body with error (machine code) and message (human-readable). HTTP status follows standard semantics.

Error response shape 
{
  "error": "runbook_not_found",
  "message": "Runbook rb_abc123 does not exist in this workspace."
}

Next steps