API reference

KYE Protocol™ Status API

7 operations · status.yaml

KYE Protocol™ Status API: try the first operations

Demo data

You learn: What a call to this API sends and gets back. You can: Send a request.

API client · Aggregated component-status report

Request
GET /api/components
Response 200
{
  "active_incidents": [
    {
      "components_affected": [
        "<components_affected>"
      ],
      "id": "<id>",
      "opened_at": "2026-10-01T09:00:00Z",
      "path": "<path>",
      "resolved_at": "2026-10-01T09:00:00Z",
      "severity": "<severity>",
      "status": "<status>",
      "title": "<title>"
    }
  ],
  "components": [
    {
      "checked_at": "2026-10-01T09:00:00Z",
      "group": "runtime",
      "id": "<id>",
      "latency_p50_ms": 1,
      "latency_p95_ms": 1,
      "message": "<message>",
      "name": "<name>",
      "status": "operational",
      "uptime_30d": 1
    }
  ],
  "generated_at": "2026-10-01T09:00:00Z",
  "next_maintenance": {},
  "overall_status": "operational",
  "schema_version": "kye.status.report.v1",
  "summary": "<summary>"
}
How this widget is built
Demonstrates
KYE™ API
Components
  • The OpenAPI 3.1 contract
  • Request and response examples from the contract
Flow
Request → response, from the published contract. Architecture diagram
Used on
Servers
https://status.kyeprotocol.com
Version
1.0.0
Source
status.yaml

Public status surface for status.kyeprotocol.com (Cloudflare Pages Functions). No authentication — this is the status page everyone checks when something is down. Per constitution §35 STREAMING-LOGS the incident data is written event-driven by the runtime (the kye-incident-detector Worker when a §13 Resilience Loop drift event crosses a severity threshold), never hand-edited; these endpoints read the canonical D1 tables and serve cached JSON / RSS views.

Status

GET/api/componentsAggregated component-status report

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)
GET/api/incidentsLive incident list

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

nameintypedescription
limitqueryinteger
sincequerystringOnly incidents with started_at >= this ISO timestamp
componentquerystringFilter by component_id
statusquerystringFilter by incident severity state

Responses

  • 200 Incident list
  • 500 query_failed — the D1 read raised
  • 503 db_binding_missing — KYE_DB not bound on the Pages project
GET/feed.xmlRSS 2.0 incident feed

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

Subscriptions

GET/api/subscribeDescribe the subscribe contract

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
POST/api/subscribeSubscribe to incident + maintenance notifications

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)

fieldtypedescription
email requiredstring
accept requiredbooleanMust be true — privacy + transactional-email acceptance
componentsarrayOptional component-id filter; empty or missing = all components
consent_marketingbooleanOpts into the quarterly status digest

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
OPTIONS/api/subscribeCORS preflight

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)
GET/api/status/unsubscribeOne-click unsubscribe

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

nameintypedescription
id requiredquerystringSubscription id token from the email's unsubscribe link

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