KYE Protocol™ App API

Auth: Session (Clerk JWT)

Responses

• 200 OK
• 404 Tenant not yet provisioned

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt
• 404 Resource not found

Auth: Session (Clerk JWT)

Responses

• 200 OK
• 401 Missing or invalid bearer token

Auth: Session (Clerk JWT)

Responses

• 200 OK
• 401 Missing or invalid bearer token

Auth: Session (Clerk JWT)

Responses

• 200 OK
• 400 Invalid field
• 401 Missing or invalid bearer token

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt
• 404 Resource not found

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 400 entity_id required
• 403 Cross-tenant access attempt

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK
• 403 Cross-tenant access attempt
• 404 Resource not found

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 OK

Auth: Session (Clerk JWT)

Responses

• 200 OK

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 200 OK
• 400 Validation error
• 404 Library entry not found
• 409 Seal mismatch

Aggregates the tenant's decisions ledger into hourly buckets with per-verdict counts (allow / deny / review / quarantine). The window is capped at 90 days; longer windows are served by the warehouse path on the gateway-worker. Powers the usage sparkline and dashboard time-series drilldowns.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Hourly rows with decision_count, allow_count, deny_count, review_count, quarantine_count
• 400 Invalid since/until, since not before until, or window over 90 days
• 503 Required D1 / service binding not attached (db_binding_missing)

Groups the tenant's widget_calls telemetry by widget_slug over the requested window (default trailing 7 days), reporting total and successful call counts per widget.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Per-widget summary rows with widget_slug, total_calls, ok_calls
• 400 Invalid since or until timestamp
• 503 Required D1 / service binding not attached (db_binding_missing)

Honest D1 aggregates scoped to the caller's tenant — decisions today, pending reconfirmations (Purpose Permissions expiring within 30 days), open drift events, evidence packs awaiting sign-off, 24h decision breakdown, authority finality (in-force / attenuated / revoked delegations + p99 lookup), and the most active agent today. Cold tenants get flat zeros, never fabricated values.

Auth: Session (Clerk JWT)

Responses

• 200 KPI snapshot for the tenant
• 503 Required D1 / service binding not attached (db_binding_missing)

Poll fallback for clients whose EventSource connection to /stream/dashboard fails. Returns the last 50 decisions, the authority graph, the 24x7 density heatmap, the edge infra topology, and the §0.3 attestation envelope for the read. A client-supplied tenant_id that diverges from the session-resolved tenant is refused per §0.11.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Snapshot with decisions, density_heatmap, authority_graph, infra_topology, attestation
• 401 Missing or invalid bearer token
• 403 cross_tenant_smuggle_refused — client tenant_id diverges from session (refusal attestation included)
• 503 Required D1 / service binding not attached (db_binding_missing)

Long-lived text/event-stream emitting typed events — subscribe envelope on open, then decision, authority_change, metric_tick and 25-second ping heartbeats, with a closing kye.compliance.attestation.v1 envelope. Connections are capped at 5 minutes; EventSource auto-reconnect re-verifies the rotating Clerk JWT. Client-supplied tenant_id diverging from the session is refused before the stream opens (§0.11).

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 SSE stream of kye.dashboard.event.v1 frames
• 401 Missing or invalid bearer token
• 403 cross_tenant_smuggle_refused — client tenant_id diverges from session
• 503 Required D1 / service binding not attached (db_binding_missing)

Buckets the tenant's decisions by UTC day-of-week and hour-of-day into a kye.density_heatmap.v1 snapshot with per-cell allow / deny / review counts. Default window is the trailing 7 days.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 kye.density_heatmap.v1 snapshot with cells, max_cell_count, total_count, attestation
• 401 Missing or invalid bearer token
• 403 cross_tenant_smuggle_refused — client tenant_id diverges from session
• 503 Required D1 / service binding not attached (db_binding_missing)

Returns the kye.infra_topology.v1 graph (Worker, D1, Queue, R2, KV nodes plus read/write/produce/consume edges) for the kye-infra-topology web component. Each node carries the §51 No-SPOF posture; D1 status reflects whether the KYE_DB binding is reachable. Per-tenant throughput values are honest zeros until the per-binding counter export ships.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 kye.infra_topology.v1 snapshot with nodes, edges, attestation
• 401 Missing or invalid bearer token
• 403 cross_tenant_smuggle_refused — client tenant_id diverges from session

Derives a kye.authority_graph.v1 node/edge graph from the tenant's most recent 200 delegations — nodes classified by URN segment (agent / capability / scope / policy / delegate / principal), edges typed delegates_to with an in_force flag and audit_ref. Includes a §0.3 attestation envelope.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 kye.authority_graph.v1 snapshot with nodes, edges, attestation
• 401 Missing or invalid bearer token
• 403 cross_tenant_smuggle_refused — client tenant_id diverges from session
• 503 Required D1 / service binding not attached (db_binding_missing)

A wallet credential is a presentable, revocable, downstream-delegatable authority grant held by the tenant principal. Read-only — credentials enter the wallet when grants are accepted or Operating Model seals are published. KPI counts active credentials, active delegations issued, credentials presentable for at most 30 more days, and revocations in the last 30 days; includes distinct holders for the filter bar.

Auth: Session (Clerk JWT)

Responses

• 200 Credential rows (credential_id, credential_class, issuer, holder, presentable_until, status, issued_at, revoked_at) plus kpi and holders
• 503 Required D1 / service binding not attached (db_binding_missing)

Auth: Session (Clerk JWT)

Responses

• 200 Authorities, their issuers and a KPI rollup
• 503 Required D1 / service binding not attached (db_binding_missing)

Every actor bound to the tenant — principals, agents, model endpoints, tools, datasets, connectors, partners — each identified by a stable kye URN. Read-only; entities are registered through the Operating Model authoring flow, not created here. KPI counts agents, people and tools by entity class.

Auth: Session (Clerk JWT)

Responses

• 200 Entity list with id, entity_class, display_name, trust_domain, status, last_seen, plus kpi
• 503 Required D1 / service binding not attached (db_binding_missing)

The admission half of the one governed register. Validates the request against kye.entity_registration.v1, checks whether the registrant may register into this trust domain, then runs the decision engine for the action entity.register. entity.register is a consequential action, so a request carrying no recorded approval is HELD (202) and nothing is written; the row and the decision that admitted it are created together or not at all. trust_domain_id is taken from the verified session and any value supplied in the body is ignored — a caller-asserted scope is not a scope.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Admitted — entity_id plus the decision that admitted it
• 202 Held for approval — reason_code and decision reference; nothing written
• 400 Contract violation — the offending field is named
• 403 Refused — registrant may not register into this trust domain
• 503 Required D1 / service binding not attached (db_binding_missing)

Builds the full adjacency-list tree from the tenant's hierarchy nodes (delegation / containment / binding edges) with a KPI roll-up of node_count, depth, agent_count and principal_count. Read-only — the tree is derived from the operating model, not authored here.

Auth: Session (Clerk JWT)

Responses

• 200 Nested tree of nodes with node_class, label, lifecycle, edge_kind, children, plus kpi
• 503 Required D1 / service binding not attached (db_binding_missing)

Prefers the private kye-search-engine worker over a service binding (signed kye.search_result.v1 envelope, lexical mode); falls back to tenant-scoped D1 LIKE matching across the entities and decisions tables when the binding is absent or the engine errors. An empty q returns an empty hit list.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Flat hit list with id, kind, title, snippet (plus score/classification on the engine path); source field names the path taken
• 503 Required D1 / service binding not attached (db_binding_missing)

Searches the tenant's indexed event store with full-text matching; when a free-text q is supplied. All filters combine with AND; rows are newest-first. Pure read with no mutation.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Echoed query, count, result rows (entry_id, event_family_id, emitted_at, phase, actor, verdict, audit_chain_ref, framework_refs, tags), served_at
• 401 Missing or invalid bearer token
• 503 Required D1 / service binding not attached (db_binding_missing)

Newest-first decision events for the caller's tenant with a KPI block covering the last 5 minutes (decisions/min rate plus allow / review / deny percentages) and distinct capability and actor lists for filter dropdowns. Updates the tenant's last-polled cursor. Read-only — decisions are emitted by the PDP, never created here.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Decision rows, kpi (rate, allow_pct, review_pct, deny_pct), capabilities, actors
• 400 invalid_since — unparseable timestamp
• 503 Required D1 / service binding not attached (db_binding_missing)

Runs the deterministic runtime authority decision for one proposed agent action and returns the three-outcome verdict (allow | require_approval | deny), a replay-stable decision_id, a patent-safe evidence reference, a receipt verify_url, and an Ed25519-sealed, offline-verifiable Evidence Pack. Emits the full evidence-event family server-side. Auth is a minted API key (runtime:write or runtime:* scope) or a Clerk session.

Auth: API key (kye_live_ / kye_test_) / Session (Clerk JWT)

Request body (required)

Responses

• 200 Governed decision: decision (allow | require_approval | deny), reason_code (canonical vocabulary), decision_id (kye:decision:<hex>, replay-stable), evidence (patent-safe audit_reference), verify_url (receipt deep-link on evidence.html), replay_seed, latency_m…
• 400 invalid_json | missing_subject | subject_not_kye_urn | missing_action | action_malformed | missing_purpose
• 401 Missing or invalid bearer token
• 403 permission_scope_exceeded — key lacks runtime:write / runtime:*
• 429 quota_exceeded — the tenant's monthly agent_action quota is exhausted (governed refusal with a patent-safe evidence reference and quota {used, limit, remaining, resets_at}; configure via KYE_AGENT_ACTION_MONTHLY_QUOTA, 0 = unlimited).

Reads the agent_memory table, excluding forgotten records. Exposes the observable contract only — id, agent_entity_id, memory_class, purpose, created_at, signed_by_kid — plus total, distinct-agent and distinct-class counts.

Auth: Session (Clerk JWT)

Responses

• 200 Memory rows (newest 200) with total, agents_count, classes_count
• 503 Required D1 / service binding not attached (db_binding_missing)

The workflow is a projection of the six per-step rows in the onboarding_steps table — there is no separate workflow store (§0 one source of truth). Returns a single-element array when the tenant has started onboarding, otherwise an empty array.

Auth: Session (Clerk JWT)

Responses

• 200 Array of zero or one kye.onboarding.workflow.v1 objects
• 401 Missing or invalid bearer token
• 503 Required D1 / service binding not attached (db_binding_missing)

A purpose is the bounded reason any agent, connector or partner may act — every Purpose Permission grant cites one. Grants themselves live under /purpose-permissions; this registry holds the definitions.

Auth: Session (Clerk JWT)

Responses

• 200 Purpose rows (purpose_id, class, display_name, lawful_basis, active_grants, status) plus kpi
• 503 Required D1 / service binding not attached (db_binding_missing)

Mints a kye:purpose URN for the tenant. The class must be a lowercase slug and the lawful basis one of the six GDPR Article 6 bases.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Created purpose with its minted purpose_id and active status
• 400 invalid_json, invalid_class, display_name_required or invalid_lawful_basis
• 503 Required D1 / service binding not attached (db_binding_missing)

Answers the least-privilege question no single existing surface answers: of the purposes this tenant declared and granted, how many were ever actually exercised? Joins the purpose registry and the grant ledger to the per-decision purpose attribution on the evidence-pack index, and classifies every declared purpose as exercised, unexercised, or not_observable. Purpose attribution only exists on decisions sealed after the decision writer began recording it, so the response reports attributed and unattributed decision counts separately and a purpose whose whole life predates the attributed window is reported as not_observable — never as unused, which would be a fabricated finding. Tenant scoping is applied in SQL on every statement.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Per-purpose findings (exercised / unexercised / not_observable), finding counts, the honest attributed and unattributed decision denominators, the observation window, unexercised live grants, and a compliance attestation
• 401 No session, or the session resolves to no tenant
• 403 A client-supplied tenant_id did not match the session-resolved tenant (§0.11 cross-tenant refusal)
• 503 Required D1 / service binding not attached (db_binding_missing)

Exposes the observable contract of the Data Mapping Agent — seal_id, asset_count, flow_count, pii_assets, sealed_at, signed_by_kid — newest first (up to 200), with the latest seal's totals lifted to top-level asset_total / flow_total / pii_assets.

Auth: Session (Clerk JWT)

Responses

• 200 Seal rows plus latest-seal totals
• 503 Required D1 / service binding not attached (db_binding_missing)

Every classification is tenant-scoped and Ed25519-signed (the signing kid is recorded). KPI counts special-category and restricted assets plus rows still pending a signature.

Auth: Session (Clerk JWT)

Responses

• 200 Classification rows (classification_id, asset_id, classification, detection, confidence, signature_kid, effective_at) plus kpi
• 503 Required D1 / service binding not attached (db_binding_missing)

Records the classification exactly as submitted (effective immediately); signature_kid is stored as supplied — empty until the record is signed.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Created classification with its minted classification_id
• 400 invalid_json, asset_id_required, invalid_classification, invalid_detection or confidence_must_be_0_to_1
• 503 Required D1 / service binding not attached (db_binding_missing)

Backs the KYE™ Publisher Access Ledger™ dashboard — the tenant's licensed-vs-breach split, the advisory GBP 500-per-Product accrual per operator, and the possible-spoof surfacing. Every snapshot is tenant-scoped (newest first, up to 200) and the KPI totals sum snapshots / breach_events / possible_spoof_events / accrued_total. The schedule is ADVISORY (§70): the publisher-claimable accrual from attribution signals, never a KYE-metered charge; unknown/unattributed access is never invoiced and possible-spoof is surfaced, not invoiced as certain.

Auth: Session (Clerk JWT)

Responses

• 200 ok, contract_url, honesty{advisory,basis}, kpi roll-up and snapshots[] (each with summary + operators + effective_at)
• 503 Required D1 / service binding not attached (db_binding_missing)

Accepts a kye.crawler_classification.v1 report (records[]) from the collector (Tier A edge or Tier C log ingest), derives the advisory breach schedule via the ONE canonical breach-schedule engine (never re-implemented, §0), and records the tenant-scoped snapshot. The customer-visible response carries a patent-safe evidence reference built only by the canonical publicEvidence() helper (§0.35).

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 ok, snapshot{snapshot_id, summary, operators, honesty, effective_at} and a patent-safe evidence reference
• 400 invalid_json, report_records_required or invalid_report
• 503 Required D1 / service binding not attached (db_binding_missing)

Tenant-visible history of GRC-export imports — source tool, target kind, format and row / mapped / error counts for the latest 100 batches.

Auth: Session (Clerk JWT)

Responses

• 200 Import history rows
• 503 Required D1 / service binding not attached (db_binding_missing)

Forwards the upload to the single canonical mapping engine (kye-evidence-import-worker) over a service binding with the worker bearer, then records the import for tenant-visible history. Fails closed — with no service binding or bearer configured the request is refused with 503 rather than silently passing content through unmapped. Content is capped at 5 MiB of decoded text.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 200 Import summary (rows, mapped, errors) plus the mapped kye.connector.evidence_import.v1 batch
• 400 invalid_json, source_tool_required, invalid_format, invalid_target_kind or content_required
• 413 content_too_large — over the 5 MiB cap
• 502 mapping_failed or import_service_unreachable — the mapping engine errored
• 503 Required D1 / service binding not attached (db_binding_missing)

Joins the tenant's decision ledger to its sealed-pack index on decision_id and reports coverage as covered / decisions, plus the full list of decisions that resolve to no pack. Breakdowns are returned per verdict, per capability and per day. dimensions reports how many rows actually carry each decision axis, so an axis the ledger does not record reads as unrecorded rather than as an empty finding. Tenant scoping is applied in SQL on both sides of the join.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Coverage totals, per-verdict / per-capability / per-day breakdowns, axis-recording health, and the uncovered-decision list
• 400 Invalid since/until, or since not before until
• 503 Required D1 / service binding not attached (db_binding_missing)

Evidence Packs are signed audit-ready envelopes for each governed action window. This is the console-level registry view; sealing and signing mechanics live in the runtime.

Auth: Session (Clerk JWT)

Responses

• 200 Pack rows (window, actions, sealed_at, status, sha256, compilation_seal, size_bytes, signers)
• 503 Required D1 / service binding not attached (db_binding_missing)

Opens a draft pack for the chosen window (default daily) with zero actions and no signers.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Created draft pack
• 400 invalid_json
• 503 Required D1 / service binding not attached (db_binding_missing)

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 The pack row with parsed signers array
• 404 Resource not found
• 503 Required D1 / service binding not attached (db_binding_missing)

Appends the caller as a signer; the pack advances from awaiting_signoff to attested once three signers have signed. Each caller may sign only once.

Auth: Session (Clerk JWT)

Parameters

Request body

Responses

• 200 Updated signers list and status
• 400 unsupported_action
• 404 Resource not found
• 409 already_signed_by_caller
• 503 Required D1 / service binding not attached (db_binding_missing)

Backs the GovernedUI approval queue (envelope kye.governedui.action_proposal.v1). Optional risk-level and approval-mode filters; KPI counts pending / approved / rejected / escalated proposals.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Proposal rows (proposal_id, actor_id, action_type, target_system, risk_level, approval_mode, state, proposed_at, decided_at, decided_by) plus kpi
• 503 Required D1 / service binding not attached (db_binding_missing)

Console-level slice of the shared decisions ledger — each row maps a decision to its action_id, actor, capability, verdict, reason_code and decided_at, newest first.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Action rows derived from the decisions ledger
• 503 Required D1 / service binding not attached (db_binding_missing)

Merges the explicit agents registry with per-agent activity derived from the decisions ledger (decision_count, last_seen_at, allow / review / deny counts). Registry rows are authoritative for metadata; agents observed only in decisions appear with null metadata. Sorted by last activity.

Auth: Session (Clerk JWT)

Responses

• 200 Merged agent list with registry metadata and activity counts
• 503 Required D1 / service binding not attached (db_binding_missing)

Mints a kye:agent URN. New agents start in the pilot lifecycle state with zero activity — no fabricated counts.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Registered agent in lifecycle_state pilot
• 400 invalid_json or missing_label
• 503 Required D1 / service binding not attached (db_binding_missing)

Cost, latency, token counts, purpose binding and evidence link for every model invocation; reconciles to provider invoices. Includes tenant-level KPI aggregates and distinct purpose / model lists for filter dropdowns.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Call rows plus kpis (calls, cost_total, tokens, avg_latency) and distinct purposes/models
• 503 Required D1 / service binding not attached (db_binding_missing)

Returns endpoint metadata only. The signing secret is stored (KYE™ must sign each outbound delivery with it) but is NEVER returned here — only a short non-usable hint. Includes a 30-day delivery summary per endpoint.

Auth: Session (Clerk JWT)

Responses

• 200 Endpoint list for the caller's tenant
• 401 Missing or invalid bearer token
• 503 Database binding unavailable

Registers an HTTPS endpoint for governance-event delivery. The signing secret is generated server-side and returned EXACTLY once — no endpoint will hand it back. Plain http is refused rather than downgraded. One active subscription per endpoint URL per tenant.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Endpoint registered; signing secret returned once
• 400 Invalid JSON, non-HTTPS or malformed URL, or unknown signal type
• 401 Missing or invalid bearer token
• 409 An active subscription already exists for this endpoint URL
• 503 Database binding unavailable

Tenant-scoped read. An id belonging to another tenant resolves to 404, never to another tenant's record (§0.11).

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Endpoint detail
• 401 Missing or invalid bearer token
• 404 Unknown endpoint for this tenant

Disables rather than row-deletes: webhook_deliveries rows reference subscriber_id, so a hard delete would orphan the delivery history the §30 audit trail depends on. Deliveries stop immediately. Idempotent — disabling an already-disabled endpoint returns 200 with idempotent true.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Endpoint disabled (or already disabled)
• 401 Missing or invalid bearer token
• 404 Unknown endpoint for this tenant

Returns key metadata only — id, label, display prefix, scope, env, created_by/at, last_used_at, revoked_at. The secret is never stored; only its SHA-256 hash is persisted.

Auth: Session (Clerk JWT)

Responses

• 200 Key metadata rows (no secrets)
• 503 Required D1 / service binding not attached (db_binding_missing)

Mints a kye_<live|test>_ key with 192 bits of entropy. The plaintext secret is returned exactly once in this response; only its SHA-256 hash and 12-character display prefix are persisted. Unrecognised scopes are dropped; an empty scope defaults to runtime:read.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Key metadata (incl. expires_at) plus the one-time plaintext secret, an Authority Finality receipt (patent-safe evidence), and a copy-now warning
• 400 invalid_json, missing_label or invalid_ttl
• 503 Required D1 / service binding not attached (db_binding_missing)

Sets status=revoked + revoked_at on the tenant's key and emits kye.admin.api_key.revoked.v1 to the WORM chain. Idempotent revocations of an already-revoked or unknown key return 404.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Revoked — returns id, revoked_at and an Authority Finality receipt
• 404 not_found_or_already_revoked
• 503 Required D1 / service binding not attached (db_binding_missing)

Mints a successor key inheriting the predecessor's scope/env, marks the predecessor status=rotated with a bounded grace window (default 3600s, during which it still verifies before it expires), and emits kye.admin.api_key.rotated.v1 to the WORM chain. The plaintext successor secret is returned exactly once. The executable form of continuously re-earned authority (§0.33).

Auth: Session (Clerk JWT)

Parameters

Request body

Responses

• 201 Successor key metadata + one-time secret + Authority Finality receipt
• 404 not_found_or_not_active
• 503 Required D1 / service binding not attached (db_binding_missing)

The doctrine-core path (§0.30 agent principal, §0.33 Authority Finality™): an agent obtains a SHORT-LIVED, HEARTBEAT-BOUND bearer key whose authority must be continuously re-earned. The key carries a near-term expiry and a heartbeat binding; missing the check-in loses the mandate (#160). Governed identically to human issuance (§0.3 evidence family + metering). Kill- switchable via KYE_KEY_AUTHORITY_AGENT_ISSUE_DISABLED.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Short-lived key metadata (incl. expires_at + heartbeat) + one-time secret + Authority Finality receipt
• 400 invalid_json or missing_principal_id
• 403 agent_issuance_disabled (kill-switch)
• 503 Required D1 / service binding not attached (db_binding_missing)

Re-earns a heartbeat-bound key's authority: a renewal MUST pass a fresh admissibility check (§12 PDP) within the heartbeat window, extending expires_at by one interval and stamping last_heartbeat_at. A renewal outside the window is denied — the mandate is already lost and the key must be re-issued. This is authority as a STATE you continuously re-earn, not a grant you keep. Governed (§0.3) + metered (§23).

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Renewed — new expires_at + Authority Finality receipt
• 403 heartbeat_window_missed or not_a_heartbeat_key
• 404 not_found_or_not_active
• 503 Required D1 / service binding not attached (db_binding_missing)

Apps are tenant-installed AI agents, copilots, runbooks and partner-supplied integrations operating under the tenant's Operating Model. KPI counts active (calls in last 24h), shadow-mode and suspended apps.

Auth: Session (Clerk JWT)

Responses

• 200 App rows (app_id, category, display_name, mode, status, calls_24h) plus kpi
• 503 Required D1 / service binding not attached (db_binding_missing)

Mints a kye:app URN. A freshly installed app starts active with zero call counts; shadow mode logs decisions without enforcing them.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Installed app with its minted app_id
• 400 invalid_json, invalid_category, display_name_required or invalid_mode
• 503 Required D1 / service binding not attached (db_binding_missing)

Assurance cards are time-bounded signed attestations mapping real evidence to regulatory framework controls, on a 90-day rotation per §0.3. KPI counts active, expiring (within 30 days), expired cards and distinct frameworks covered.

Auth: Session (Clerk JWT)

Responses

• 200 Card rows (card_id, framework, controls, scope, status, attested_at, expires_at, verifier_url) plus kpi
• 503 Required D1 / service binding not attached (db_binding_missing)

Mints a kye:assurance-card URN with honest timestamps — attested now, expiring 90 days later — and a public verifier URL. Controls must be a non-empty array of control identifiers.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Created card with verifier_url and a 90-day expires_at
• 400 invalid_json, invalid_framework, scope_required or controls_required_array
• 503 Required D1 / service binding not attached (db_binding_missing)

Each row stores prev_hash and a SHA-256 hash over the canonical JSON of (seq, event, actor, summary, at, prev_hash) so the chain is client-verifiable by recomputing from seq=1. Rows are returned newest first.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Event rows with seq, event, actor, summary, at, prev_hash, hash
• 503 Required D1 / service binding not attached (db_binding_missing)

Appends the next sequence entry, linking prev_hash to the prior row (or a 64-zero genesis) and hashing the canonical JSON. Normally driven by the runtime; exposed so admins can record compliance markers such as a manually attested evidence pack.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Appended event with its seq, prev_hash and hash
• 400 invalid_json or missing_event
• 503 Required D1 / service binding not attached (db_binding_missing)

Returns the highest revision of the tenant's behaviour model (allowed actions, obligations, stop-conditions, escalation paths). A tenant with no model yet gets revision 0 with empty rows.

Auth: Session (Clerk JWT)

Responses

• 200 Latest revision with rows, signed flag, updated_at, updated_by
• 503 Required D1 / service binding not attached (db_binding_missing)

Inserts a new unsigned revision; prior revisions are kept immutable for sign-off and replay. Rows are shape-validated and capped at 500; string fields are length-clamped.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 200 New revision number, accepted row count and updated_at
• 400 invalid_json or rows_array_required
• 503 Required D1 / service binding not attached (db_binding_missing)

Reads the canonical kye_grants store (binding KYE_GRANTS_DB, populated by the commercial-lifecycle worker's Stripe projection): latest subscription, up to 50 invoices with hosted Stripe URLs, and attestation seats. Returns 503 db_binding_missing until the KYE_GRANTS_DB binding is attached to the Pages project.

Auth: Session (Clerk JWT)

Responses

• 200 subscription (or null), invoices, seats
• 503 Required D1 / service binding not attached (db_binding_missing)

Pure function per §23 §4 — 3 basis points on the transaction value with a £5 floor and £50 cap. The only supported action is bps_simulate.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 200 Fee breakdown: rate_bps, computed_fee_pence, final_fee_pence, was_floored, was_capped
• 400 invalid_json or unsupported_action
• 503 Required D1 / service binding not attached (db_binding_missing)

Connectors bring outside-system events into the tenant's KYE™ evidence stream; the canonical kind vocabulary is kye:dictionary:connectors. KPI counts healthy, degraded and disconnected connectors.

Auth: Session (Clerk JWT)

Responses

• 200 Connector rows (connector_id, kind, profile_family, display_name, status, last_harvest_at, events_24h) plus kpi
• 503 Required D1 / service binding not attached (db_binding_missing)

Mints a kye:connector URN. A freshly installed connector is disconnected until its first authenticated harvest — honest initial state, no fabricated health.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Installed connector in disconnected status
• 400 invalid_json, invalid_kind, display_name_required or invalid_profile_family
• 503 Required D1 / service binding not attached (db_binding_missing)

Authority flows actor to principal to subject under a scope with an expiry; attenuations are separate rows referencing a parent_id. State is derived lazily — revoked when revoked_at is set, expired when past expires_at, otherwise active.

Auth: Session (Clerk JWT)

Responses

• 200 Delegation rows with derived state (active / expired / revoked)
• 503 Required D1 / service binding not attached (db_binding_missing)

Issues a delegation with a TTL (default 365 days, max 730). When attenuating via parent_id, the parent must exist and belong to the caller's tenant.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Created delegation with expires_at
• 400 invalid_json or missing_fields
• 404 parent_not_found — attenuation parent missing or not owned by this tenant
• 503 Required D1 / service binding not attached (db_binding_missing)

Sets revoked_at / revoked_by and flips state to revoked; an optional reason is recorded.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Revoked — returns id and revoked_at
• 404 not_found_or_already_revoked
• 503 Required D1 / service binding not attached (db_binding_missing)

The runtime opens drift events automatically; humans close them. Optional state filter; counts power the tab badges.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Event rows (type, actor, severity, opened, closed, resolution) plus open/closed counts
• 503 Required D1 / service binding not attached (db_binding_missing)

Records a meaning-continuity drift marker. Unrecognised types default to meaning_broken and unrecognised severities to P2.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Opened event with its id and opened timestamp
• 400 invalid_json
• 503 Required D1 / service binding not attached (db_binding_missing)

Marks the event closed with a resolution; unrecognised or absent resolutions default to remediated. The resolver identity is recorded.

Auth: Session (Clerk JWT)

Parameters

Request body

Responses

• 200 Closed — returns id, closed timestamp, resolution, resolved_by
• 404 not_found_or_already_closed
• 503 Required D1 / service binding not attached (db_binding_missing)

Returns only the non-allow decisions (deny, reject, revoke, quarantine, require_approval, require_human_review) for the caller's tenant, clustered by reason_code x capability x actor_entity_id and ranked on each axis separately. Each cluster reports how many of its refusals resolve to an Evidence Pack. dimensions reports the real recording coverage of each axis over the refused set — reason_code is null on historical rows and populates from newer decisions forward, and a null is never inferred or defaulted. Tenant scoping is applied in SQL.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Refusal totals, per-axis rankings, axis-recording health, and the reason_code x capability x actor clusters
• 400 Invalid since/until, or since not before until
• 503 Required D1 / service binding not attached (db_binding_missing)

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Matching decision records
• 400 `invalid_since`
• 503 Required D1 / service binding not attached (db_binding_missing)

Listings are the tenant's public-facing entries in the KYE™ Directory — rule packs, agents, connectors, assurance cards — each requiring moderation before becoming visible. KPI counts published, in-review and draft listings plus removals in the last 90 days.

Auth: Session (Clerk JWT)

Responses

• 200 Listing rows (listing_id, listing_type, title, status, views_30d) plus kpi
• 503 Required D1 / service binding not attached (db_binding_missing)

Mints a kye:listing URN. A new listing starts as draft — it must be submitted and pass moderation before becoming visible; view counts start at zero.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Created draft listing
• 400 invalid_json, invalid_listing_type, title_required or title_too_long
• 503 Required D1 / service binding not attached (db_binding_missing)

Auth: Session (Clerk JWT)

Responses

• 200 Partner rows (name, class, assurance tier, status, since, onboarded_by)
• 503 Required D1 / service binding not attached (db_binding_missing)

Registers a third-party partner under the tenant's authority. Unrecognised assurance values default to Tier 3 and unrecognised statuses to active.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Onboarded partner with its minted id
• 400 invalid_json or missing_fields
• 503 Required D1 / service binding not attached (db_binding_missing)

Plugins are tenant-side extensions of the protocol — PDP rule packs, conformance probes, custom obligations, SDK shims. KPI counts enabled, failing and update-available plugins.

Auth: Session (Clerk JWT)

Responses

• 200 Plugin rows (plugin_id, kind, display_name, version, state, health, invocations_24h, update_available) plus kpi
• 503 Required D1 / service binding not attached (db_binding_missing)

Mints a kye:plugin URN. A freshly installed plugin is disabled until the tenant enables it in the decision flow — honest initial state. Version must be semver-shaped.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Installed plugin in disabled state
• 400 invalid_json, invalid_kind, display_name_required or invalid_version
• 503 Required D1 / service binding not attached (db_binding_missing)

Every action under a KYE-governed agent must cite an issued Purpose Permission. Status is derived per row — revoked, pending_reconfirm (past expiry), expiring (within 30 days) or active.

Auth: Session (Clerk JWT)

Responses

• 200 Grant rows (grantee, purpose, scope, expires, derived status, issued/revoked/reconfirmed audit fields)
• 503 Required D1 / service binding not attached (db_binding_missing)

Issues an active grant with a TTL (default 90 days, max 365). The issuer identity is recorded from the session.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Issued grant with expires timestamp
• 400 invalid_json or missing_fields
• 503 Required D1 / service binding not attached (db_binding_missing)

Extends the grant by ttl_days (default 90, max 365) from now, records last_reconfirmed_at and resets status to active. Revoked grants cannot be reconfirmed.

Auth: Session (Clerk JWT)

Parameters

Request body

Responses

• 200 New expires, last_reconfirmed_at and reconfirmed_by
• 404 not_found_or_revoked
• 503 Required D1 / service binding not attached (db_binding_missing)

Sets revoked_at / revoked_by and flips status to revoked; an optional reason is recorded.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Revoked — returns id and revoked_at
• 404 not_found_or_already_revoked
• 503 Required D1 / service binding not attached (db_binding_missing)

Replay runs reference an evidence_pack_id and are signed via kye.replay.proof.v1; divergence opens a Resilience Loop ticket automatically. KPI reports replays in the last 24h, overall match rate, divergences in the last 30 days and signature failures.

Auth: Session (Clerk JWT)

Responses

• 200 Run rows (replay_id, evidence_pack_id, decision_id, verdict, signature_ok, requested/completed timestamps) plus kpi
• 503 Required D1 / service binding not attached (db_binding_missing)

Queues a run in the pending verdict — only the Replay Engine may resolve it to verified, diverged or signature_failed. Signature status is unknown (false) until the engine runs.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Queued run in pending verdict
• 400 invalid_json or evidence_pack_id_required
• 503 Required D1 / service binding not attached (db_binding_missing)

Assessments are tenant-scoped, audit-chained and framework-floor-governed. KPI counts prohibited verdicts in the last 24h plus high, limited and minimal tiers across the latest 500 assessments.

Auth: Session (Clerk JWT)

Responses

• 200 Assessment rows (assessment_id, subject_id, subject_class, tier, score, reason_codes, framework_floor, effective_at) plus kpi
• 503 Required D1 / service binding not attached (db_binding_missing)

Records the assessment exactly as submitted — no fabricated scores or tier upgrades. Score is an integer 0-100.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Recorded assessment with its minted assessment_id
• 400 invalid_json, subject_id_required, invalid_subject_class, invalid_tier, score_must_be_0_to_100 or invalid_framework_floor
• 503 Required D1 / service binding not attached (db_binding_missing)

Scopes are capability + dataset + jurisdiction triples bounding what an agent may do within a granted purpose. KPI counts active scopes, scopes bound to at least one purpose, total datasets and distinct jurisdictions.

Auth: Session (Clerk JWT)

Responses

• 200 Scope rows (scope_id, capability, datasets, jurisdiction, bound_purposes, status) plus kpi
• 503 Required D1 / service binding not attached (db_binding_missing)

Mints a kye:scope URN. A freshly declared scope starts active with zero purpose bindings — bindings are created through the Purpose Permission rail. Datasets accept an array or comma-separated string.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Declared scope with zero purpose bindings
• 400 invalid_json, invalid_capability or invalid_jurisdiction
• 503 Required D1 / service binding not attached (db_binding_missing)

An assignment binds a tenant state machine to a specific entity and tracks its current state. KPI counts assignments, distinct bound entities, transitions in the last 24h and assignments with no transition in 30 days (stuck); includes distinct entity classes for the filter bar.

Auth: Session (Clerk JWT)

Responses

• 200 Assignment rows (assignment_id, state_machine_id, entity_id, entity_class, current_state, state_since, last_transition_at, transitions_24h) plus kpi and entity_classes
• 503 Required D1 / service binding not attached (db_binding_missing)

Verifies the referenced state machine exists and belongs to the caller's tenant, then creates the assignment in the given initial state (default pending) with zero transitions.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Created assignment in its initial state
• 400 invalid_json, state_machine_id_required, entity_id_required or entity_class_required
• 404 state_machine_not_found_or_not_owned
• 503 Required D1 / service binding not attached (db_binding_missing)

Creates a subscription-mode Checkout Session via the Stripe REST API, stamping the tenant id into client_reference_id and metadata, and persists a checkout intent so the webhook can correlate checkout.session.completed back to the tenant. The client redirects to the returned url.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 200 session_id, hosted checkout url and expires_at
• 400 invalid_json or bad_price_id
• 502 stripe_error — Stripe API rejected the request
• 503 Required D1 / service binding not attached (db_binding_missing)

Reads the canonical invoices table in the kye_grants store (binding KYE_GRANTS_DB), populated by the commercial-lifecycle worker's Stripe projection. Hosted Stripe invoice URLs are passed straight through.

Auth: Session (Clerk JWT)

Responses

• 200 Invoice rows with totals, status, hosted URL and billing period (latest 100)
• 503 Required D1 / service binding not attached (db_binding_missing)

Looks up the tenant's stripe_customer_id from its most recent non-cancelled subscription in the kye_grants store, then creates a Billing Portal session returning to /billing.html.

Auth: Session (Clerk JWT)

Responses

• 200 Portal url for the caller's Stripe customer
• 404 no_active_subscription — create one via /stripe/checkout-session first
• 502 stripe_error — Stripe API rejected the request
• 503 Required D1 / service binding not attached (db_binding_missing)

Month-to-date decision count, evidence packs created, AI cost and token totals, a 4-week weekly decision sparkline, and a 30-day meter summary grouped by meter class. Honest zeros when tables are empty.

Auth: Session (Clerk JWT)

Responses

• 200 decisions_month, evidence_packs_month, ai_cost_month, ai_tokens_month, weekly_decisions, meters
• 503 Required D1 / service binding not attached (db_binding_missing)

Resolves the brand config through the tenant's active consultant link, preferring a tenant-specific row over the consultant-wide default. Read-only.

Auth: Session (Clerk JWT)

Responses

• 200 Brand config (brand_name, colours, logo_url, domain, support_email, legal_footer)
• 401 Missing or invalid bearer token
• 404 No active white-label config applies to this tenant
• 503 db_binding_missing or white-label tables not provisioned

Each widget carries its own licence and revocation path; the embed CDN returns 410 once a widget is revoked.

Auth: Session (Clerk JWT)

Responses

• 200 Widget rows (kind, host, pages, licence, status, installed, views_30d, revoked_at)
• 503 Required D1 / service binding not attached (db_binding_missing)

Mints a kye:widget URN with a fresh 24-character embed key and returns the ready-to-paste embed snippet pointing at the widget CDN.

Auth: Session (Clerk JWT)

Request body (required)

Responses

• 201 Created widget with embed_key and embed_snippet
• 400 invalid_json or missing_kind
• 503 Required D1 / service binding not attached (db_binding_missing)

Issues a fresh 24-character embed key for an unrevoked widget. The only supported action is rotate.

Auth: Session (Clerk JWT)

Parameters

Request body (required)

Responses

• 200 New embed_key for the widget
• 400 unsupported_action
• 404 not_found_or_revoked
• 503 Required D1 / service binding not attached (db_binding_missing)

Flips status to revoked and sets revoked_at; the embed CDN then serves 410 for this widget.

Auth: Session (Clerk JWT)

Parameters

Responses

• 200 Revoked — returns id and revoked_at
• 404 not_found_or_already_revoked
• 503 Required D1 / service binding not attached (db_binding_missing)