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

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

GET/api/v1/reality-anchorsList reality anchors

Auth: bearerAuth

Parameters

name	in	type
`tenant_id`	query	string
`anchor_type`	query	string
`status`	query	string
`q`	query	string

Responses

200 OK

POST/api/v1/reality-anchorsCreate 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}/verifyMark 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}/deprecateMark 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-snapshotsList reality snapshots

Auth: bearerAuth

Parameters

name	in	type
`tenant_id`	query	string
`anchor_id`	query	string
`is_stale`	query	string
`since`	query	string

Responses

200 OK

POST/api/v1/reality-snapshotsRecord 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}/verifyMark 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-checksList coupling checks

Auth: bearerAuth

Parameters

name	in	type
`tenant_id`	query	string
`action_id`	query	string
`coupling_result`	query	string
`since`	query	string

Responses

200 OK

POST/api/v1/reality-coupling-checksRecord 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}/checkRun/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}/decideRecord 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-eventsList stable-drift events

Auth: bearerAuth

Parameters

name	in	type
`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-eventsOpen 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}/acknowledgeAcknowledge 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}/resolveResolve 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}/quarantineQuarantine 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