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

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

GET/api/ep/mattersList 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/mattersCreate 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}/reviewRecord 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