---
title: "KYE Protocol™ — Scenario Testing™ + Approval Brief™ API | API reference"
description: "KYE Protocol™ — Scenario Testing™ + Approval Brief™ API: 56 operations from scenario-testing.openapi.yaml, a published KYE Protocol™ OpenAPI contract."
url: https://kyeprotocol.com/developers/api/scenario-testing/
lang: en
source: "KYE Protocol"
---

> KYE Protocol™ — Scenario Testing™ + Approval Brief™ API: 56 operations from scenario-testing.openapi.yaml, a published KYE Protocol™ OpenAPI contract.

API reference

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

56 operations · `scenario-testing.openapi.yaml`

**Servers**

`https://admin.kyeprotocol.com` `https://app.kyeprotocol.com`

**Version**

1.0.0

**Source**

[scenario-testing.openapi.yaml](https://kyeprotocol.com/developers/api/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 29 approval-brief 27

## scenario-testing

GET `/api/v1/scenarios` List scenarios

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `tenant_id` | query | string |  |
| `run_mode` | query | string |  |
| `status` | query | string |  |
| `q` | query | string |  |

### Responses

- `200` OK

POST `/api/v1/scenarios` Create 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-runs` List 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

- `200` OK

POST `/api/v1/scenario-runs` Queue 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}/rerun` Replay 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-evidence` Create 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-tests` List stress tests (admin)

**Auth:** bearerAuth

### Parameters

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

### Responses

- `200` OK

POST `/api/v1/stress-tests` Create 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}/rerun` Execute 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/stressors` List stressor library entries (admin)

**Auth:** bearerAuth

### Parameters

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

### Responses

- `200` OK

POST `/api/v1/stressors` Create 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-maps` List 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-maps` Create 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}/verify` Verify 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-briefs` List approval briefs

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `tenant_id` | query | string |  |
| `approver` | query | string |  |
| `status` | query | string |  |

### Responses

- `200` OK

POST `/api/v1/approval-briefs` Create 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}/viewed` Mark 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}/acknowledge` Approver acknowledges the brief (idempotent)

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `id` **required** | path | string |  |

### Responses

- `200` OK

GET `/api/v1/approver-knowledge-snapshots` List 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-snapshots` Create 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-decisions` List approval decisions

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `tenant_id` | query | string |  |
| `approver` | query | string |  |
| `decision` | query | string |  |
| `since` | query | string |  |

### Responses

- `200` OK

POST `/api/v1/approval-decisions` Record 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}/revoke` Revoke 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}/expire` Mark an approval decision expired (idempotent)

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `id` **required** | path | string |  |

### Responses

- `200` OK

GET `/api/v1/approval-evidence-packs` List 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-packs` Create 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}/export` Download a self-contained JSON bundle of the evidence pack

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `id` **required** | path | string |  |

### Responses

- `200` Bundle