Incidents API

Manage incidents programmatically, create them (which queues them for automatic triage), list and filter them, update status and ownership, add comments, and work with follow-up actions.

Base path: /api/v1/incidents · Permission resource: incident (actions read, write, delete). All requests require authentication.

Endpoints

Create an incident

POST /api/v1/incidents/: the incident is created and automatically queued for triage.

Request body:

curl -s -X POST "http://localhost:8000/api/v1/incidents/" \
  -H "Authorization: Bearer $CLOUDPEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Suspicious IAM key usage",
        "description": "Access key used from a new geography.",
        "severity": "high",
        "priority": "P2",
        "source_tool": "aws_guardduty",
        "source_alert_name": "UnauthorizedAccess:IAMUser/ConsoleLogin",
        "source_alert_id": "abc-123",
        "source_alert_type": "guardduty_finding",
        "source_metadata": { "region": "us-east-1" }
      }'
# → 201 Created

List incidents

GET /api/v1/incidents/ supports filtering, sorting and pagination via query parameters:

curl -s "http://localhost:8000/api/v1/incidents/?priority=P1&sort_by=created_at&sort_order=desc&limit=25" \
  -H "Authorization: Bearer $CLOUDPEEK_TOKEN"
# → { "incidents": [ … ], "total": 37, "offset": 0, "limit": 25 }

The incident object

A returned incident includes (among others):

id, title, description, status, severity, priority, source_tool, source_alert_name, source_alert_id, source_alert_type, alert_count, assigned_to, assignees, triage_result, triage_summary, recommendations, followup_actions, created_at, updated_at, triage_started_at, triage_completed_at, outcome_approval_status, outcome_rejection_reason.

The triage_* fields are populated by automatic triage, and followup_actions reflects the investigation plan.

Update an incident

PATCH /api/v1/incidents/{incident_id}: all fields optional: title, description, severity, priority, status, assigned_to_id, outcome_approval_status, outcome_rejection_reason. Recording a rejected triage outcome requires a rejection reason.

Assign and comment

• POST /incidents/{incident_id}/assign: body { "assignee_ids": ["user-1", "user-2"] }.
• POST /incidents/{incident_id}/comments: body { "comment": "…", "is_internal": false }.

Follow-up actions

Retry follow-up actions that failed, individually or in bulk, and list failures across the tenant. See Follow-up Actions for what these are.

Related

• Incident Management: the UI for all of the above.
• Automatic Triage: what happens after you create an incident.