REST contract for the cyber/AI incident system. Base resource /api, JSON format, header-based authentication (Bearer / x-konsult-secret). Per-endpoint authorization depends on role (see Roles & Priorities).
/api/ip3/incidents, /api/ip3/stats, /api/ip3/playbooks actually work (SIMULATION data) — try them in the API Explorer. Machine contract: openapi.json. The operational registry /api/incidents and all writes (POST/PATCH) are protected / production (OIDC/mTLS — ROADMAP).200 OK, 201 Created, 202 Accepted (async intake), 400 validation, 401/403 authorization, 409 state conflict (e.g. closing without evidence), 422 evidence-first doctrine violation.hash_sha256 wherever binary material is involved.422 rule: a PATCH that changes status_lifecycle to closed without an associated validation_ref is rejected.| Method | Path | Min. role | Description |
|---|---|---|---|
| POST | /api/incidents | Reporter | Create an incident (defaults to gap). |
| GET | /api/incidents | Viewer | List with filters (priority, level, flags, status). |
| GET | /api/incidents/:id | Viewer | Incident detail with evidence and actions. |
| PATCH | /api/incidents/:id | Analyst | Update classification/status/flags. |
| POST | /api/incidents/:id/evidence | Analyst | Attach evidence (kind, hash, confidence, custody). |
| GET | /api/incidents/:id/evidence | Viewer* | Incident evidence (visibility filtered by role). |
| POST | /api/incidents/:id/actions | Operator | Add a response step from a playbook. |
| PATCH | /api/actions/:id | Operator | Update step status; HITL approve. |
| GET | /api/map/incidents | Viewer | Data for the Threat Map (geo/sector/time). |
| GET | /api/stats/incidents | Viewer | KPI aggregates for the dashboard. |
| GET | /api/playbooks | Viewer | Playbook index. |
| GET | /api/playbooks/:type | Viewer | Steps for a playbook of a given type. |
| POST | /api/intake/osint | Operator | OSINT submission (entry status media/public). |
| POST | /api/intake/log | DevSecOps | SIEM/EDR log submission (internal). |
| POST | /api/agents/:id/quarantine | AI Safety | Quarantine an agent (revoke privileges). |
| POST | /api/agents/:id/restore | AI Safety | Restore an agent after validation. |
| POST | /api/reports/incidents/:id/export | Legal/DPO | Export a report to an authority (NIS2/GDPR/AI Act). |
* Viewer* — a Public Viewer sees only visibility=public evidence; restricted/internal require an Analyst+ role.
Request SIMULATION:
POST /api/incidents
Content-Type: application/json
{
"title": "Suspected prompt injection in a support agent",
"source_type": "form",
"level": "L2_ai",
"category": "prompt_injection",
"detected_at": "2026-07-04T08:12:00Z",
"agent_id": "b1f2...-agent",
"impact_integrity": 2,
"gdpr_personal_data": true
}
Response SIMULATION:
201 Created
{
"id": "9c0a...-inc",
"public_id": "INC-2026-0042",
"evidence_status": "gap",
"priority": null,
"status_lifecycle": "open",
"sla_due_at": null,
"flags": { "ai_act_relevant": true, "gdpr_personal_data": true },
"created_at": "2026-07-04T08:12:03Z"
}
priority=null. Priority and any status promotion are granted only by classification after evidence exists (Classification Engine).POST /api/incidents/INC-2026-0042/evidence // SIMULATION
{
"kind": "agent_trace",
"source": "orchestrator-logs",
"content_ref": "s3://evidence/trace-0042.json",
"hash_sha256": "3b1f...e9",
"confidence": 82,
"visibility": "internal",
"chain_of_custody": [
{"ts":"2026-07-04T08:20:00Z","actor":"analyst:kdzik","action":"collected","hash_after":"3b1f...e9"}
]
}
--> 201 Created { "id":"ev-771", "status":"confirmed" }
// aggregation raises incidents.evidence_status: gap -> confirmed
PATCH /api/incidents/INC-2026-0042 // SIMULATION
{ "priority": "P1", "severity": 7, "ai_serious_incident": true }
--> 200 OK { "sla_due_at":"2026-07-05T08:12:03Z", "nis2_relevant":true }
// attempt to close without remediation evidence:
PATCH /api/incidents/INC-2026-0042 { "status_lifecycle":"closed" }
--> 422 Unprocessable Entity
{ "error":"evidence_required",
"detail":"Closure requires a response_action with a validation_ref (remediation evidence)." }
POST /api/agents/b1f2...-agent/quarantine // SIMULATION
{ "incident_id":"INC-2026-0042", "reason":"prompt_injection_confirmed",
"approved_by":"aiso:mpaw" }
--> 200 OK
{ "status":"quarantined","current_score":34,"trust_delta":-66,
"allowed_tools_effective":[] }
Quarantine revokes effective privileges regardless of allowed_tools. Restoration (/restore) requires the AI Safety Officer role and validation evidence (see the agent hijack playbook).
POST /api/reports/incidents/INC-2026-0042/export // SIMULATION
{ "target":"csirt_nask", "regime":"nis2", "phase":"early_warning_24h" }
--> 202 Accepted
{ "report_id":"RPT-0042-1", "regime":"nis2", "phase":"24h",
"bundle":["incident","evidence(public,restricted)","timeline"],
"delivery":"edelivery_pending" }
The export selects its scope by regime: NIS2 (24h early warning → 72h notification → final report), GDPR art. 33 (72h to the supervisory authority), AI Act art. 73 (serious incident). Delivery is confirmed by a UPO/e-Delivery receipt, which returns as evidence of type upo_edelivery. Regime details: Compliance.
GET /api/stats/incidents?window=30d // SIMULATION
--> 200 OK
{ "total":128, "open_p0_p1":7, "evidence_coverage":0.94,
"flags":{"ai_serious_incident":3,"nis2_relevant":11,"gdpr_breach":5},
"mtta_p0_min":131, "mttc_p1_h":18, "_note":"demonstration data" }