API reference

KYE Protocol™ — Scenario Testing™ + Approval Brief™ API

56 operations · scenario-testing.openapi.yaml

Scenario Testing™ + Approval Brief™ API: try the first operations

Demo data

You learn: What a call to this API sends and gets back. You can: Send a request.

API client · List scenarios

Request

GET /api/v1/scenarios

Response `200`

{
  "ok": true,
  "scenarios": [
    {
      "created_at": "2026-10-01T09:00:00Z",
      "created_by": "<created_by>",
      "description": "<description>",
      "id": "<id>",
      "name": "<name>",
      "run_mode": "what_if",
      "status": "draft",
      "tags": [
        "<tags>"
      ],
      "target_object_id": "<target_object_id>",
      "target_object_schema": "<target_object_schema>",
      "tenant_id": "<tenant_id>",
      "updated_at": "2026-10-01T09:00:00Z",
      "version": 1
    }
  ],
  "total": 1
}

API client · Fetch a scenario

Request

GET /api/v1/scenarios/%3Cid%3E

Response `200`

{
  "ok": true,
  "scenario": {
    "created_at": "2026-10-01T09:00:00Z",
    "created_by": "<created_by>",
    "description": "<description>",
    "id": "<id>",
    "name": "<name>",
    "run_mode": "what_if",
    "status": "draft",
    "tags": [
      "<tags>"
    ],
    "target_object_id": "<target_object_id>",
    "target_object_schema": "<target_object_schema>",
    "tenant_id": "<tenant_id>",
    "updated_at": "2026-10-01T09:00:00Z",
    "version": 1
  }
}

API client · List scenario runs

Request

GET /api/v1/scenario-runs

Response `200`

{
  "ok": true,
  "scenario_runs": [
    {
      "admit_count": 1,
      "consequence_map_id": "<consequence_map_id>",
      "deny_count": 1,
      "ended_at": "2026-10-01T09:00:00Z",
      "escalate_count": 1,
      "id": "<id>",
      "risk_score": 1,
      "run_mode": "<run_mode>",
      "scenario_id": "<scenario_id>",
      "started_at": "2026-10-01T09:00:00Z",
      "status": "queued",
      "summary": "<summary>",
      "tenant_id": "<tenant_id>"
    }
  ],
  "total": 1
}

How this widget is built

Demonstrates

KYE™ API

Components

The OpenAPI 3.1 contract
Request and response examples from the contract

Flow

Request → response, from the published contract. Architecture diagram

Used on

/developers/api/scenario-testing/: On every contract's reference page.

Servers: https://admin.kyeprotocol.com https://app.kyeprotocol.com
Version: 1.0.0
Source: 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
`tenant_id`	query	string
`run_mode`	query	string
`status`	query	string
`q`	query	string

Responses

200 OK

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

201 Created
400 Validation error

GET/api/v1/scenarios/{id}Fetch a scenario

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not 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

200 OK

DELETE/api/v1/scenarios/{id}Soft-delete a scenario (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

GET/api/v1/scenario-runsList scenario runs

Auth: bearerAuth

Parameters

name	in	type
`tenant_id`	query	string
`scenario_id`	query	string
`run_mode`	query	string
`since`	query	string

Responses

200 OK

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

202 Accepted

GET/api/v1/scenario-runs/{id}Fetch a scenario run

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not 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

200 OK

DELETE/api/v1/scenario-runs/{id}Soft-delete a scenario run (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

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

202 Accepted

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

202 Accepted

GET/api/v1/stress-testsList stress tests (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`tenant_id`	query	string
`status`	query	string

Responses

200 OK

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

201 Created

GET/api/v1/stress-tests/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not 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

200 OK

DELETE/api/v1/stress-tests/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

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

202 Accepted

GET/api/v1/stressorsList stressor library entries (admin)

Auth: bearerAuth

Parameters

name	in	type	description
`tenant_id`	query	string
`category`	query	string

Responses

200 OK

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

201 Created

GET/api/v1/stressors/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not 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

200 OK

DELETE/api/v1/stressors/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

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

200 OK

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

201 Created

GET/api/v1/consequence-maps/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not 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

200 OK

DELETE/api/v1/consequence-maps/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

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

200 Verified
422 Verification failed

approval-brief

GET/api/v1/approval-briefsList approval briefs

Auth: bearerAuth

Parameters

name	in	type
`tenant_id`	query	string
`approver`	query	string
`status`	query	string

Responses

200 OK

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

201 Created

GET/api/v1/approval-briefs/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not 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

200 OK

DELETE/api/v1/approval-briefs/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

POST/api/v1/approval-briefs/{id}/viewedMark a brief as viewed (idempotent)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

POST/api/v1/approval-briefs/{id}/acknowledgeApprover acknowledges the brief (idempotent)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

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

200 OK

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

201 Created

GET/api/v1/approver-knowledge-snapshots/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not 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

200 OK

DELETE/api/v1/approver-knowledge-snapshots/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

POST/api/v1/approver-knowledge-snapshots/{id}/verify

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 Verified
422 Verification failed

GET/api/v1/approval-decisionsList approval decisions

Auth: bearerAuth

Parameters

name	in	type
`tenant_id`	query	string
`approver`	query	string
`decision`	query	string
`since`	query	string

Responses

200 OK

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

201 Created

GET/api/v1/approval-decisions/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not 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

200 OK

DELETE/api/v1/approval-decisions/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

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

200 OK

POST/api/v1/approval-decisions/{id}/expireMark an approval decision expired (idempotent)

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

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

200 OK

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

201 Created

GET/api/v1/approval-evidence-packs/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK
404 Not 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

200 OK

DELETE/api/v1/approval-evidence-packs/{id}

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 OK

POST/api/v1/approval-evidence-packs/{id}/verify

Auth: bearerAuth

Parameters

name	in	type	description
`id` required	path	string

Responses

200 Verified
422 Verification 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

200 Bundle

Related

KYE Protocol™ Admin Root EndpointsKYE Protocol™ Admin Root Endpoints: 3 operations from admin-root.yaml, a published KYE Protocol™ OpenAPI contract.
KYE Protocol™ Admin APIKYE Protocol™ Admin API: 188 operations from admin.yaml, a published KYE Protocol™ OpenAPI contract.
KYE Protocol™ Cloud Partner-Plane APIKYE Protocol™ Cloud Partner-Plane API: 18 operations from app-partner.yaml, a published KYE Protocol™ OpenAPI contract.
KYE Protocol™ App API (API reference)KYE Protocol™ App API — root paths: 3 operations from app-root.yaml, a published KYE Protocol™ OpenAPI contract.
KYE Protocol™ App APIKYE Protocol™ App API: 132 operations from app.yaml, a published KYE Protocol™ OpenAPI contract.

KYE Protocol™ — Scenario Testing™ + Approval Brief™ API

Request

Response 200

Request

Response 200

Request

Response 200

scenario-testing

Parameters

Responses

Parameters

Request body (required)

Responses

Parameters

Responses

Parameters

Request body (required)

Responses

Parameters

Responses

Parameters

Responses

Parameters

Request body (required)

Responses

Parameters

Responses

Parameters

Request body (required)

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Request body (required)

Responses

Parameters

Responses

Parameters

Request body (required)

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Request body (required)

Responses

Parameters

Responses

Parameters

Request body (required)

Responses

Parameters

Responses

Parameters

Responses

Parameters

Request body (required)

Responses

Parameters

Responses

Parameters

Request body (required)

Responses

Parameters

Responses

Parameters

Responses

approval-brief

Parameters

Responses

Parameters

Response `200`

Response `200`

Response `200`