API reference
KYE Protocol™ — Scenario Testing™ + Approval Brief™ API
56 operations · scenario-testing.openapi.yaml
Admin authoring (owner-gated) and tenant-scoped read endpoints for the KYE™ Scenario Testing™ + Approval Brief™ surface.
All POST endpoints accept an Idempotency-Key header; if present, the response is cached per (tenant_id, scope, key) and returned verbatim on retry. Soft-delete only — deleted_at is set; the row is never physically removed.
Base path: /api/v1/
scenario-testing
GET/api/v1/scenariosList scenarios
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id | query | string | |
run_mode | query | string | |
status | query | string | |
q | query | string |
Responses
200OK
POST/api/v1/scenariosCreate a scenario (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
Idempotency-Key | header | string |
Request body (required)
| field | type | description |
|---|---|---|
tenant_id required | string | |
name required | string | |
description | string | |
run_mode required | string | One of what_if, stress_test, blast_radius, future_state, revocation_impact, approval_risk |
target_object required | object | |
inputs | object | |
stressors | array | |
validity | object | |
tags | array |
Responses
201Created400Validation error
GET/api/v1/scenarios/{id}Fetch a scenario
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK404Not found
PATCH/api/v1/scenarios/{id}Update a scenario (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Request body (required)
| field | type | description |
|---|---|---|
name | string | |
description | string | |
status | string | One of draft, active, archived |
tags | array | |
inputs | object | |
stressors | array |
Responses
200OK
DELETE/api/v1/scenarios/{id}Soft-delete a scenario (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK
GET/api/v1/scenario-runsList scenario runs
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id | query | string | |
scenario_id | query | string | |
run_mode | query | string | |
since | query | string |
Responses
200OK
POST/api/v1/scenario-runsQueue a scenario run (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
Idempotency-Key | header | string |
Request body (required)
| field | type | description |
|---|---|---|
tenant_id required | string | |
scenario_id required | string | |
run_mode required | string | |
target_object required | object | |
resolved_inputs | object | |
started_at | string |
Responses
202Accepted
GET/api/v1/scenario-runs/{id}Fetch a scenario run
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK404Not found
PATCH/api/v1/scenario-runs/{id}Update a scenario run outcome (admin / runner)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Request body (required)
| field | type | description |
|---|---|---|
status | string | |
ended_at | string | |
admit_count | integer | |
deny_count | integer | |
escalate_count | integer | |
risk_score | number | |
summary | string | |
consequence_map_id | string | |
divergence_from_baseline | boolean | |
signed_by | string | |
signature | object |
Responses
200OK
DELETE/api/v1/scenario-runs/{id}Soft-delete a scenario run (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK
POST/api/v1/scenario-runs/{id}/rerunReplay a scenario run (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string | |
Idempotency-Key | header | string |
Responses
202Accepted
POST/api/v1/scenario-runs/{id}/generate-evidenceCreate an approval evidence pack from a scenario run (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string | |
Idempotency-Key | header | string |
Responses
202Accepted
GET/api/v1/stress-testsList stress tests (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id | query | string | |
status | query | string |
Responses
200OK
POST/api/v1/stress-testsCreate a stress test (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
Idempotency-Key | header | string |
Request body (required)
| field | type | description |
|---|---|---|
tenant_id required | string | |
name required | string | |
description | string | |
target_object required | object | |
stressors | array | |
severity | string | One of low, medium, high, critical |
Responses
201Created
GET/api/v1/stress-tests/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK404Not found
PATCH/api/v1/stress-tests/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Request body (required)
| field | type | description |
|---|---|---|
name | string | |
description | string | |
severity | string | One of low, medium, high, critical |
status | string | |
stressors | array |
Responses
200OK
DELETE/api/v1/stress-tests/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK
POST/api/v1/stress-tests/{id}/rerunExecute a stress test (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string | |
Idempotency-Key | header | string |
Responses
202Accepted
GET/api/v1/stressorsList stressor library entries (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id | query | string | |
category | query | string |
Responses
200OK
POST/api/v1/stressorsCreate a stressor library entry (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
Idempotency-Key | header | string |
Request body (required)
| field | type | description |
|---|---|---|
tenant_id | string | |
stressor_id required | string | |
name required | string | |
description | string | |
category | string | |
default_severity | string | One of low, medium, high, critical |
parameters | object |
Responses
201Created
GET/api/v1/stressors/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK404Not found
PATCH/api/v1/stressors/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Request body (required)
| field | type | description |
|---|---|---|
name | string | |
description | string | |
category | string | |
default_severity | string | One of low, medium, high, critical |
parameters | object |
Responses
200OK
DELETE/api/v1/stressors/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK
GET/api/v1/consequence-mapsList consequence maps (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id | query | string | |
scenario_run_id | query | string |
Responses
200OK
POST/api/v1/consequence-mapsCreate a consequence map (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
Idempotency-Key | header | string |
Request body (required)
| field | type | description |
|---|---|---|
tenant_id required | string | |
scenario_run_id | string | |
target_object required | object | |
nodes | array | |
edges | array | |
summary | string |
Responses
201Created
GET/api/v1/consequence-maps/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK404Not found
PATCH/api/v1/consequence-maps/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Request body (required)
| field | type | description |
|---|---|---|
summary | string | |
nodes | array | |
edges | array | |
content_hash | string | |
signature | object |
Responses
200OK
DELETE/api/v1/consequence-maps/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK
POST/api/v1/consequence-maps/{id}/verifyVerify the signature on a consequence map (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200Verified422Verification failed
approval-brief
GET/api/v1/approval-briefsList approval briefs
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id | query | string | |
approver | query | string | |
status | query | string |
Responses
200OK
POST/api/v1/approval-briefsCreate an approval brief (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
Idempotency-Key | header | string |
Request body (required)
| field | type | description |
|---|---|---|
tenant_id required | string | |
proposed_action required | object | |
approver required | string | |
knowledge_snapshot_id required | string | |
consequence_map_id required | string | |
supporting_scenario_runs | array | |
recommended_decision | string | One of approved, approved_with_restrictions, rejected, expired, escalated, requires_more_information |
validity required | object |
Responses
201Created
GET/api/v1/approval-briefs/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK404Not found
PATCH/api/v1/approval-briefs/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Request body (required)
| field | type | description |
|---|---|---|
recommended_decision | string | |
status | string | |
validity_not_after | string | |
signature | object |
Responses
200OK
DELETE/api/v1/approval-briefs/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK
POST/api/v1/approval-briefs/{id}/viewedMark a brief as viewed (idempotent)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK
POST/api/v1/approval-briefs/{id}/acknowledgeApprover acknowledges the brief (idempotent)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK
GET/api/v1/approver-knowledge-snapshotsList approver knowledge snapshots (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id | query | string | |
approver | query | string |
Responses
200OK
POST/api/v1/approver-knowledge-snapshotsCreate an approver knowledge snapshot (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
Idempotency-Key | header | string |
Request body (required)
| field | type | description |
|---|---|---|
tenant_id required | string | |
approver required | string | |
captured_at | string | |
source_refs | array | |
content_hash | string | |
summary | string |
Responses
201Created
GET/api/v1/approver-knowledge-snapshots/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK404Not found
PATCH/api/v1/approver-knowledge-snapshots/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Request body (required)
| field | type | description |
|---|---|---|
summary | string | |
content_hash | string | |
source_refs | array | |
signature | object |
Responses
200OK
DELETE/api/v1/approver-knowledge-snapshots/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK
POST/api/v1/approver-knowledge-snapshots/{id}/verify
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200Verified422Verification failed
GET/api/v1/approval-decisionsList approval decisions
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id | query | string | |
approver | query | string | |
decision | query | string | |
since | query | string |
Responses
200OK
POST/api/v1/approval-decisionsRecord an approval decision (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
Idempotency-Key | header | string |
Request body (required)
| field | type | description |
|---|---|---|
tenant_id required | string | |
approval_brief_id required | string | |
approver required | string | |
decision required | string | One of approved, approved_with_restrictions, rejected, expired, escalated, requires_more_information |
decided_at | string | |
rationale required | string | |
restrictions | array | |
escalated_to | string | |
knowledge_snapshot_id | string |
Responses
201Created
GET/api/v1/approval-decisions/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK404Not found
PATCH/api/v1/approval-decisions/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Request body (required)
| field | type | description |
|---|---|---|
rationale | string | |
restrictions | array | |
escalated_to | string | |
signature | object |
Responses
200OK
DELETE/api/v1/approval-decisions/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK
POST/api/v1/approval-decisions/{id}/revokeRevoke an approval decision
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Request body (required)
| field | type | description |
|---|---|---|
reason required | string |
Responses
200OK
POST/api/v1/approval-decisions/{id}/expireMark an approval decision expired (idempotent)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK
GET/api/v1/approval-evidence-packsList approval evidence packs
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id | query | string | |
approval_brief_id | query | string |
Responses
200OK
POST/api/v1/approval-evidence-packsCreate an approval evidence pack (admin)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
Idempotency-Key | header | string |
Request body (required)
| field | type | description |
|---|---|---|
tenant_id required | string | |
approval_brief_id | string | |
knowledge_snapshot_id | string | |
consequence_map_id | string | |
approval_decision_id | string | |
supporting_scenario_runs | array |
Responses
201Created
GET/api/v1/approval-evidence-packs/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK404Not found
PATCH/api/v1/approval-evidence-packs/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Request body (required)
| field | type | description |
|---|---|---|
status | string | |
content_hash | string | |
sealed_at | string | |
sealed_by | string | |
signature | object |
Responses
200OK
DELETE/api/v1/approval-evidence-packs/{id}
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200OK
POST/api/v1/approval-evidence-packs/{id}/verify
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200Verified422Verification failed
GET/api/v1/approval-evidence-packs/{id}/exportDownload a self-contained JSON bundle of the evidence pack
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
id required | path | string |
Responses
200Bundle