---
title: "KYE Protocol™ App API — root paths | API reference"
description: "KYE Protocol™ App API — root paths: 3 operations from app-root.yaml, a published KYE Protocol™ OpenAPI contract."
url: https://kyeprotocol.com/developers/api/app-root/
lang: en
source: "KYE Protocol"
---

> KYE Protocol™ App API — root paths: 3 operations from app-root.yaml, a published KYE Protocol™ OpenAPI contract.

API reference

# KYE Protocol™ App API — root paths

3 operations · `app-root.yaml`

**Servers**

`https://app.kyeprotocol.com`

**Version**

1.0.0

**Source**

[app-root.yaml](https://kyeprotocol.com/developers/api/app-root.yaml)

Companion document to app.yaml (whose server base is https://app.kyeprotocol.com/api/v1) for app-surface Pages-Functions endpoints that live OUTSIDE the /api/v1 base path.

Currently: the KYE™ Estate Planning Authority Console™ (§49 §9 estate-planning) matter + review endpoints under /api/ep. This is a §33 HYBRID surface — the public Pages Function owns the Clerk-JWT auth boundary (via /\_middleware.js) and persists to D1 (binding KYE\_DB); the IP-track estate engine is the downstream processor.

Every privileged operation emits a §0.3 evidence-envelope chain (kye.purpose.request.v1 → kye.purpose.admissibility.v1 → kye.evidence.decision\_map.v1 → kye.compliance.attestation.v1, plus kye.engagement.approval.v1 on review decisions). The admissibility envelope's `admissible` flag is bound by its contract: True iff every required reason check passed. The engine MUST set this consistently with the reasons array. The chain is returned base64-encoded in the x-kye-governance-chain response header and persisted append-only to ep\_governance\_events (WORM triggers, migration 035). Tenant isolation per §0.11: every D1 query carries a trust\_domain\_id predicate resolved from the JWT.

EstatePlanning 3

## EstatePlanning

GET `/api/ep/matters` List estate-planning matters for the caller's tenant

Tenant-scoped list (WHERE trust\_domain\_id = caller's tenant, §0.11), newest first. Emits the §0.3 envelope chain for operation ep\_listMatters and persists it to ep\_governance\_events.

**Auth:** Session (Clerk JWT)

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `status` | query | string | Filter by matter lifecycle status (exact match) |
| `limit` | query | integer |  |

### Responses

- `200` Tenant-scoped matter list
- `401` No verified Clerk session on the request
- `503` D1 binding KYE\_DB is not configured on the Pages project

POST `/api/ep/matters` Create an estate-planning matter

Creates a matter bound to the authenticated tenant + engagement with status 'open'. matter\_type must be one of the canonical types and client\_full\_name must be at least 2 characters. Emits + persists the §0.3 envelope chain for operation ep\_createMatter.

**Auth:** Session (Clerk JWT)

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `matter_type` **required** | string | One of will\_standard, will\_complex, lpa\_property, lpa\_health, trust, other |
| `client_full_name` **required** | string |  |
| `client_ref` | string | Optional client reference (truncated to 100 chars) |

### Responses

- `201` Matter created
- `400` Invalid JSON body, unknown matter\_type, or client\_full\_name too short
- `401` No verified Clerk session on the request
- `503` D1 binding KYE\_DB is not configured on the Pages project

POST `/api/ep/matters/{id}/review` Record a manager / supervising-solicitor review decision

Records a review decision on a matter. The matter is fetched with BOTH matter\_id AND trust\_domain\_id predicates — a matter owned by a different tenant returns 404, never a 403 that leaks existence (§0.11). §27 dual-channel enforcement: the approver must differ from the matter creator (self-approval is denied 403), and irreversible decisions (block | escalate) require a dual\_channel\_attestation\_id. Writes to ep\_matter\_reviews + ep\_governance\_events (append-only WORM) and emits the §0.3 chain for operation ep\_submitReviewDecision, including kye.engagement.approval.v1.

**Auth:** Session (Clerk JWT)

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `id` **required** | path | string | Matter id (kye:ep:matter:<uuid>) |

### Request body (required)

| field | type | description |
| --- | --- | --- |
| `decision` **required** | string | One of approve, return, escalate, block |
| `dual_channel_attestation_id` | string | §27 dual-channel attestation envelope id. Required when decision is block or escalate. |
| `notes` | string |  |

### Responses

- `201` Review decision recorded
- `400` Missing matter id, invalid JSON body, or decision not in approve | return | escalate | block
- `401` No verified Clerk session on the request
- `403` §27 dual-channel denial — self-approval (approver equals the matter preparer), or an irreversible decision without a dual\_channel\_attestation\_id.
- `404` Matter not found in the caller's tenant (cross-tenant ids return 404, not 403)
- `503` D1 binding KYE\_DB is not configured on the Pages project