KYE Protocol™ Status API

Returns a kye.status.report.v1 payload aggregated from the canonical component inventory, recent health rows in D1 (kye_status_components), and unresolved incidents (kye_status_incidents). Overall status is the worst-case of all components. Served through a 60-second KV cache to prevent thundering-herd polling; the x-cache response header reports HIT or MISS. CORS-open (Access-Control-Allow-Origin: *) so any surface can embed the status widget.

Responses

• 200 Status report (cached up to 60s)

Reads the canonical incidents D1 table (event-driven writes per §35 — never hand-edited) and returns a filterable JSON list, newest first, with a 15-second edge cache.

Parameters

Responses

• 200 Incident list
• 500 query_failed — the D1 read raised
• 503 db_binding_missing — KYE_DB not bound on the Pages project

RSS 2.0 feed of the 50 most recent incidents, regenerated on each request from the live incidents D1 table with a 60-second edge cache. Per §35, downstream consumers (RSS readers, status aggregators, on-call channels) subscribe to this feed instead of polling the HTML page. If the D1 read fails the endpoint emits an empty but valid feed rather than a 5xx — status RSS is critical infrastructure.

Responses

• 200 RSS 2.0 XML document

Self-describing helper — returns the expected POST body shape for /api/subscribe (field names, requiredness, semantics) so the form and third-party integrators can introspect the contract without reading source.

Responses

• 200 Machine-readable description of the POST contract

Stores a subscription row in D1 (status_subscriptions, migration 013) and sends a confirmation email through the canonical §38 Comms Engine template status.subscribe.confirmation.v1. Idempotent — an email that is already subscribed returns the existing subscription id with already_subscribed: true instead of creating a duplicate. Spam controls: a honeypot field (website) silently accepts and ignores bot submissions, and submissions are rate-limited to 5 per day-salted IP hash per 24h window.

Request body (required)

Responses

• 200 Subscribed (or already subscribed — idempotent)
• 400 invalid_body, invalid_email, or terms_not_accepted
• 429 rate_limited — more than 5 subscriptions from the same IP hash in 24h
• 500 handler_exception — unexpected failure (message included, truncated to 500 chars)
• 503 not_provisioned — KYE_DB unbound or migration 013_status_subscriptions.sql not applied

CORS preflight for the subscribe form. Allows origin https://status.kyeprotocol.com with methods GET, POST, OPTIONS and the content-type request header; preflight result cacheable for 86400 seconds.

Responses

• 204 Preflight accepted (no body)

One-click unsubscribe for status notifications, linked from every status.subscribe.confirmation.v1 email (RFC 8058 spirit — GET by design, since the link is clicked straight from an email client and the id token is an unguessable kye:status-sub:<uuid>). Idempotent: re-hitting an already-unsubscribed token returns ok: true with already: true. The suppression is recorded to the audit chain (event_family internal.status.unsubscribe) when AUDIT_CHAIN_BASE_URL is configured; emission failures are logged loudly, never swallowed.

Parameters

Responses

• 200 Unsubscribed (idempotent)
• 400 missing_token — id absent or not a kye:status-sub:<uuid>
• 404 unknown_token — no live subscription with that id
• 500 handler_exception — unexpected failure
• 503 not_provisioned — KYE_DB unbound or migration 013_status_subscriptions.sql not applied