---
title: "KYE Protocol™ — Reality Coupling™ API | API reference"
description: "KYE Protocol™ — Reality Coupling™ API: 25 operations from reality-coupling.openapi.yaml, a published KYE Protocol™ OpenAPI contract."
url: https://kyeprotocol.com/developers/api/reality-coupling/
lang: en
source: "KYE Protocol"
---

> KYE Protocol™ — Reality Coupling™ API: 25 operations from reality-coupling.openapi.yaml, a published KYE Protocol™ OpenAPI contract.

API reference

# KYE Protocol™ — Reality Coupling™ API

25 operations · `reality-coupling.openapi.yaml`

**Servers**

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

**Version**

1.0.0

**Source**

[reality-coupling.openapi.yaml](https://kyeprotocol.com/developers/api/reality-coupling.openapi.yaml)

Admin authoring (owner-gated) and tenant-scoped read endpoints for the KYE™ Reality Coupling™ surface — reality anchors, snapshots, runtime coupling checks, and stable-drift events.

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.

V1.1 endpoints (assumptions, revalidation requests, coupling evidence packs, cross-system consistency checks) are intentionally deferred and NOT documented here.

Base path: /api/v1/

reality-coupling 25

## reality-coupling

GET `/api/v1/reality-anchors` List reality anchors

**Auth:** bearerAuth

### Parameters

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

### Responses

- `200` OK

POST `/api/v1/reality-anchors` Create a reality anchor (admin)

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | string |  |

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `tenant_id` **required** | string |  |
| `anchor_type` **required** | string | One of system\_of\_record, external\_source\_of\_truth, policy\_context, risk\_context, market\_context, environment\_state, clinical\_context, financial\_context, infrastructure\_context, vendor\_context, identity\_context |
| `display_name` **required** | string |  |
| `description` | string |  |
| `authority` **required** | object |  |
| `freshness_contract` | object |  |
| `grounds_actions` | array |  |
| `grounds_profiles` | array |  |
| `source` | object |  |
| `tags` | array |  |

### Responses

- `201` Created
- `400` Validation error

GET `/api/v1/reality-anchors/{id}` Fetch a reality anchor

**Auth:** bearerAuth

### Parameters

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

### Responses

- `200` OK
- `404` Not found

PATCH `/api/v1/reality-anchors/{id}` Update a reality anchor (admin)

**Auth:** bearerAuth

### Parameters

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

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `display_name` | string |  |
| `description` | string |  |
| `status` | string | One of draft, active, deprecated |
| `freshness_contract` | object |  |
| `grounds_actions` | array |  |
| `grounds_profiles` | array |  |
| `source` | object |  |
| `tags` | array |  |

### Responses

- `200` OK

DELETE `/api/v1/reality-anchors/{id}` Soft-delete a reality anchor (admin)

**Auth:** bearerAuth

### Parameters

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

### Responses

- `200` OK

POST `/api/v1/reality-anchors/{id}/verify` Mark an anchor as verified (admin)

**Auth:** bearerAuth

### Parameters

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

### Responses

- `200` OK

POST `/api/v1/reality-anchors/{id}/deprecate` Mark an anchor as deprecated (admin)

**Auth:** bearerAuth

### Parameters

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

### Request body

| field | type | description |
| --- | --- | --- |
| `reason` | string |  |

### Responses

- `200` OK

GET `/api/v1/reality-snapshots` List reality snapshots

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `tenant_id` | query | string |  |
| `anchor_id` | query | string |  |
| `is_stale` | query | string |  |
| `since` | query | string |  |

### Responses

- `200` OK

POST `/api/v1/reality-snapshots` Record a reality snapshot (admin)

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | string |  |

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `tenant_id` **required** | string |  |
| `anchor_id` **required** | string |  |
| `anchor_type` | string | One of system\_of\_record, external\_source\_of\_truth, policy\_context, risk\_context, market\_context, environment\_state, clinical\_context, financial\_context, infrastructure\_context, vendor\_context, identity\_context |
| `sampled_at` **required** | string |  |
| `valid_until` | string |  |
| `source_version` | string |  |
| `content_hash` **required** | string |  |
| `content_summary` | object |  |
| `content_ref` | string |  |
| `freshness` | object |  |
| `observations` | array |  |
| `tags` | array |  |
| `signature` | object |  |

### Responses

- `201` Created

GET `/api/v1/reality-snapshots/{id}`

**Auth:** bearerAuth

### Parameters

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

### Responses

- `200` OK
- `404` Not found

DELETE `/api/v1/reality-snapshots/{id}`

**Auth:** bearerAuth

### Parameters

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

### Responses

- `200` OK

POST `/api/v1/reality-snapshots/{id}/verify` Mark a snapshot as verified (admin)

**Auth:** bearerAuth

### Parameters

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

### Responses

- `200` OK

GET `/api/v1/reality-coupling-checks` List coupling checks

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `tenant_id` | query | string |  |
| `action_id` | query | string |  |
| `coupling_result` | query | string |  |
| `since` | query | string |  |

### Responses

- `200` OK

POST `/api/v1/reality-coupling-checks` Record a coupling check (admin)

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | string |  |

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `tenant_id` **required** | string |  |
| `action_id` **required** | string |  |
| `actor_entity_id` | string |  |
| `principal_entity_id` | string |  |
| `purpose_grant_id` | string |  |
| `evaluated_at` | string |  |
| `pipeline_node` | string |  |
| `anchors_consulted` | array |  |
| `assumptions` | array |  |
| `coupling_result` **required** | string | One of coupled, coupled\_with\_warnings, decoupling\_detected, revalidation\_required, quarantine\_required, deny\_required, unknown |
| `runtime_effect` **required** | string | One of continue, continue\_with\_warning, require\_revalidation, require\_human\_review, quarantine, deny |
| `severity` | string | One of low, medium, high, critical |
| `reason_codes` | array |  |
| `drift_event_id` | string |  |
| `snapshot_refs` | array |  |
| `evidence_refs` | array |  |
| `notes` | string |  |

### Responses

- `201` Created

GET `/api/v1/reality-coupling-checks/{id}`

**Auth:** bearerAuth

### Parameters

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

### Responses

- `200` OK
- `404` Not found

DELETE `/api/v1/reality-coupling-checks/{id}`

**Auth:** bearerAuth

### Parameters

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

### Responses

- `200` OK

POST `/api/v1/reality-coupling-checks/{id}/check` Run/re-run a coupling check via the engine (admin)

**Auth:** bearerAuth

### Parameters

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

### Responses

- `202` Accepted

POST `/api/v1/reality-coupling-checks/{id}/decide` Record an owner decision on a coupling check (admin)

**Auth:** bearerAuth

### Parameters

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

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `decision` **required** | string | One of override, accept, escalate |
| `rationale` | string |  |

### Responses

- `200` OK

GET `/api/v1/stable-drift-events` List stable-drift events

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `tenant_id` | query | string |  |
| `status` | query | string |  |
| `severity` | query | string |  |
| `drift_type` | query | string |  |
| `since` | query | string |  |

### Responses

- `200` OK

POST `/api/v1/stable-drift-events` Open a stable-drift event (admin)

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | string |  |

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `tenant_id` **required** | string |  |
| `check_id` **required** | string |  |
| `action_id` **required** | string |  |
| `actor_entity_id` | string |  |
| `principal_entity_id` | string |  |
| `drift_type` **required** | string | One of stable\_drift, verified\_but\_stale, source\_of\_truth\_stale, operational\_context\_stale, policy\_context\_shifted, environment\_state\_mismatch, system\_of\_record\_conflict, assumption\_expired, semantic\_anchor\_drift, cross\_… |
| `severity` **required** | string | One of low, medium, high, critical |
| `detected_at` | string |  |
| `anchors_implicated` | array |  |
| `expected_state` | object |  |
| `observed_state` | object |  |
| `description` | string |  |
| `reason_codes` | array |  |
| `recommended_runtime_effect` | string | One of continue, continue\_with\_warning, require\_revalidation, require\_human\_review, quarantine, deny |
| `recommended_obligations` | array |  |
| `evidence_refs` | array |  |

### Responses

- `201` Created

GET `/api/v1/stable-drift-events/{id}`

**Auth:** bearerAuth

### Parameters

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

### Responses

- `200` OK
- `404` Not found

DELETE `/api/v1/stable-drift-events/{id}`

**Auth:** bearerAuth

### Parameters

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

### Responses

- `200` OK

POST `/api/v1/stable-drift-events/{id}/acknowledge` Acknowledge a drift event (admin)

**Auth:** bearerAuth

### Parameters

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

### Request body

| field | type | description |
| --- | --- | --- |
| `note` | string |  |

### Responses

- `200` OK

POST `/api/v1/stable-drift-events/{id}/resolve` Resolve a drift event (admin)

**Auth:** bearerAuth

### Parameters

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

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `resolution` **required** | string | One of recoupled, tolerated, escalated, revoked |
| `rationale` | string |  |

### Responses

- `200` OK

POST `/api/v1/stable-drift-events/{id}/quarantine` Quarantine a drift event (admin)

**Auth:** bearerAuth

### Parameters

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

### Request body

| field | type | description |
| --- | --- | --- |
| `reason` | string |  |

### Responses

- `200` OK