Skip to content
perstatDocs

Create a manual incident

POST
/organizations/{org_id}/incidents
curl --request POST \
  --url https://api.perstat.io/organizations/example/incidents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "cause": "example", "monitor_id": "example", "severity": "example", "severity_level": "example", "started_at_unix": 1, "summary": "example" }'

Creates a manual incident, optionally linked to a monitor of the same organization. Severity defaults to critical, a business severity level (sev1 to sev3) and a backdated start time may be supplied, and configured webhooks receive an opened event. Requires the incident command plan capability, otherwise 402. Accepts API keys with the incidents:write scope, subject to current role and resource grants.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org_id
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Manuellen Incident anlegen. monitor_id optional (Public-ID) — fehlt er, ist es ein eigenständiger Incident ohne Monitor (Dienstleister-/Info-Meldung).

object
cause
string | null
monitor_id
string | null
severity

critical (Ausfall, Default) oder degraded (Einschränkung).

string | null
severity_level

Fachliche Stufe: sev1|sev2|sev3 (optional).

string | null
started_at_unix

Beginn (Unix-Sekunden); fehlt → jetzt. Für Backfill vergangener Vorfälle.

integer | null format: int64
summary
required
string
Examplegenerated
{
  "cause": "example",
  "monitor_id": "example",
  "severity": "example",
  "severity_level": "example",
  "started_at_unix": 1,
  "summary": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

Request succeeded. The response body contains the result.

Media typeapplication/json
object
acknowledged_at_unix
integer | null format: int64
acknowledged_by_email
string | null
alarm_held_by_name
string | null
alarm_held_until_unix

Abhaengige Alarme: bis wann die Alarmkette zurueckgehalten wird (Unix-Sekunden), und WER sie haelt. Beides gehoert nach aussen , ein zurueckgehaltener Alarm, den man nicht sehen kann, ist von einem verschluckten nicht zu unterscheiden.

integer | null format: int64
auto_resolved
required
boolean
cause
required
string
check_kind
string | null
commander_email
string | null
down_regions
required
Array<string>
evidence
One of:
null
failure_phase_started_at_unix

First quorum-confirmed failure of the uninterrupted measurement phase.

integer | null format: int64
id
required
string
lifecycle_state
required
string
monitor_id
required
string
monitor_name
string | null
project_id

Stable project public id for monitor drill-down, including legacy or manual incidents without an immutable evidence snapshot.

string | null
project_name
string | null
region_count
required
integer format: int32
resolved_at_unix
integer | null format: int64
severity
required
string
severity_level
string | null
started_at_unix
required
integer format: int64
status
required
string
summary
required
string
Examplegenerated
{
  "acknowledged_at_unix": 1,
  "acknowledged_by_email": "example",
  "alarm_held_by_name": "example",
  "alarm_held_until_unix": 1,
  "auto_resolved": true,
  "cause": "example",
  "check_kind": "example",
  "commander_email": "example",
  "down_regions": [
    "example"
  ],
  "evidence": {
    "actual_summary": "example",
    "check_kind": "example",
    "checks": [
      {
        "cause_layer": "example",
        "check_id": "example",
        "checked_at_unix": 1,
        "detail": "example",
        "latency_ms": 1,
        "region": "example",
        "response_code": 1,
        "status": "example"
      }
    ],
    "confirmation_state": "example",
    "confirmed_outage_since_unix": 1,
    "consecutive_failures_observed": 1,
    "consecutive_failures_required": 1,
    "expected_regions": 1,
    "expected_summary": "example",
    "failed_regions": 1,
    "failure_class": "example",
    "findings": [
      {
        "actual_summary": "example",
        "expected_summary": "example",
        "failure_class": "example",
        "latest_checked_at_unix": 1,
        "occurrence_count": 1,
        "regions": [
          "example"
        ]
      }
    ],
    "first_failure_at_unix": 1,
    "minimum_confirmed_outage_seconds": 1,
    "monitor_id": "example",
    "monitor_name": "example",
    "project_id": "example",
    "project_name": "example",
    "reason": "example",
    "reporting_regions": 1,
    "required_regions": 1,
    "triggered_at_unix": 1,
    "version": 1
  },
  "failure_phase_started_at_unix": 1,
  "id": "example",
  "lifecycle_state": "example",
  "monitor_id": "example",
  "monitor_name": "example",
  "project_id": "example",
  "project_name": "example",
  "region_count": 1,
  "resolved_at_unix": 1,
  "severity": "example",
  "severity_level": "example",
  "started_at_unix": 1,
  "status": "example",
  "summary": "example"
}

400

Section titled “400”

The request is invalid. Check the supplied fields and values.

401

Section titled “401”

Authentication is missing or invalid.

402

Section titled “402”

The request exceeds an entitlement or limit of the current plan.

403

Section titled “403”

The authenticated caller does not have permission to perform this operation.

404

Section titled “404”

No accessible resource matches the supplied identifier.