{
  "openapi": "3.1.0",
  "info": {
    "title": "ResetPulse Public Evidence API",
    "version": "1.0.0",
    "description": "Credential-free, read-only public evidence for Codex reset signals. Public signals do not prove the private state of an individual account.",
    "license": { "name": "Public API terms", "url": "https://lydiahub.online/privacy" }
  },
  "servers": [{ "url": "https://lydiahub.online" }],
  "externalDocs": { "description": "Integration guide", "url": "https://lydiahub.online/integrate" },
  "tags": [
    { "name": "Signals", "description": "Current public signal and evidence receipt." },
    { "name": "Health", "description": "Collection freshness and coverage boundaries." },
    { "name": "Forecast", "description": "Transparent public-signal estimates with explicit uncertainty boundaries." },
    { "name": "Distribution", "description": "Read-only feeds and embeddable public artifacts." }
  ],
  "paths": {
    "/api/public-signal": {
      "get": {
        "operationId": "getPublicSignal",
        "summary": "Get the compact public signal packet",
        "description": "Returns the primary signal, newer context when present, freshness, semantic signalVersion, and the public/private boundary.",
        "tags": ["Signals"],
        "responses": { "200": { "description": "Public signal packet", "headers": { "ETag": { "$ref": "#/components/headers/SignalETag" }, "X-ResetPulse-Signal-Version": { "$ref": "#/components/headers/SignalVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicSignalPacket" } } } }, "304": { "description": "Signal version has not changed" } }
      },
      "options": { "operationId": "getPublicSignalCors", "summary": "Inspect read-only CORS support", "tags": ["Signals"], "responses": { "204": { "description": "CORS preflight response" } } }
    },
    "/api/evidence/latest": {
      "get": {
        "operationId": "getLatestEvidence",
        "summary": "Get the latest primary evidence receipt",
        "description": "Returns a resetpulse.evidence.v1 record with a SHA-256 integrity receipt. The receipt proves record integrity, not private account state.",
        "tags": ["Signals"],
        "responses": { "200": { "description": "Latest evidence receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceReceipt" } } } } }
      }
    },
    "/api/timeline": {
      "get": {
        "operationId": "getPublicTimeline",
        "summary": "Get an incrementally syncable public event timeline",
        "description": "Returns source-private public events with optional since and limit filters. Use the semantic ETag to avoid reprocessing unchanged evidence.",
        "tags": ["Signals"],
        "parameters": [
          { "name": "since", "in": "query", "required": false, "description": "Return events published after this ISO-8601 timestamp.", "schema": { "type": "string", "format": "date-time" } },
          { "name": "limit", "in": "query", "required": false, "description": "Maximum number of events to return (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }
        ],
        "responses": { "200": { "description": "Public timeline", "headers": { "ETag": { "$ref": "#/components/headers/ResourceETag" }, "X-ResetPulse-Signal-Version": { "$ref": "#/components/headers/SignalVersion" }, "X-ResetPulse-Resource-Version": { "$ref": "#/components/headers/ResourceVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Timeline" } } } }, "304": { "description": "Timeline has not changed for the requested query" }, "400": { "description": "Invalid since or limit parameter" } }
      },
      "options": { "operationId": "getPublicTimelineCors", "summary": "Inspect read-only CORS support", "tags": ["Signals"], "responses": { "204": { "description": "CORS preflight response" } } }
    },
    "/api/verified-packet": {
      "get": {
        "operationId": "getVerifiedPacket",
        "summary": "Get the public signal and its integrity receipt in one response",
        "description": "Returns a credential-free, source-private packet containing the primary public signal, newer context, freshness, and its SHA-256 evidence receipt.",
        "tags": ["Signals"],
        "responses": { "200": { "description": "Verified Reset Packet", "headers": { "ETag": { "$ref": "#/components/headers/SignalETag" }, "X-ResetPulse-Signal-Version": { "$ref": "#/components/headers/SignalVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedPacket" } } } }, "304": { "description": "Signal version has not changed" } }
      },
      "options": { "operationId": "getVerifiedPacketCors", "summary": "Inspect read-only CORS support", "tags": ["Signals"], "responses": { "204": { "description": "CORS preflight response" } } }
    },
    "/api/evidence/{id}": {
      "get": {
        "operationId": "getEvidenceById",
        "summary": "Get an evidence receipt by public event ID",
        "tags": ["Signals"],
        "parameters": [{ "$ref": "#/components/parameters/EventId" }],
        "responses": { "200": { "description": "Evidence receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceReceipt" } } } }, "404": { "description": "Receipt not found" } }
      }
    },
    "/api/propagation-trace/{id}": {
      "get": {
        "operationId": "getPropagationTrace",
        "summary": "Get the public propagation trace for an event",
        "description": "Returns source time, collector observation, a bounded source-observation ledger when available, public evidence state, and thresholded anonymous outcome state. Raw observations, fingerprints, credentials, and private account telemetry are never returned.",
        "tags": ["Signals"],
        "parameters": [{ "$ref": "#/components/parameters/EventId" }],
        "responses": { "200": { "description": "Propagation trace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropagationTrace" } } } }, "404": { "description": "Trace not found" } }
      },
      "options": { "operationId": "getPropagationTraceCors", "summary": "Inspect read-only CORS support", "tags": ["Signals"], "responses": { "204": { "description": "CORS preflight response" } } }
    },
    "/api/monitor-health": {
      "get": {
        "operationId": "getMonitorHealth",
        "summary": "Get collection freshness and evidence coverage",
        "description": "Reports collector freshness, source fetch health, corroborating-source counts, and historical timing samples when available. It is not a delivery SLA.",
        "tags": ["Health"],
        "responses": { "200": { "description": "Monitor health receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorHealth" } } } } }
      }
    },
    "/api/benchmark": {
      "get": {
        "operationId": "getPublicBenchmark",
        "summary": "Sample public monitor freshness fields side by side",
        "description": "Returns a credential-free comparison of collector checks, provider-reported public signal times, and a persistent change history when available. External timing means a public timestamp to ResetPulse observation; the response does not claim a fastest service or publish raw external payloads.",
        "tags": ["Health"],
        "responses": { "200": { "description": "Public benchmark sample", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicBenchmark" } } } }, "503": { "description": "Sample temporarily unavailable" } }
      },
      "options": { "operationId": "getPublicBenchmarkCors", "summary": "Inspect read-only CORS support", "tags": ["Health"], "responses": { "204": { "description": "CORS preflight response" } } }
    },
    "/api/reliability": {
      "get": {
        "operationId": "getReliabilityReport",
        "summary": "Get public record-quality and timing metrics",
        "description": "Returns source-private record-quality metrics, evidence coverage, and historical source-to-observation timing boundaries. It is not a delivery SLA or private account report.",
        "tags": ["Health"],
        "responses": { "200": { "description": "Public reliability report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReliabilityReport" } } } } }
      },
      "options": { "operationId": "getReliabilityReportCors", "summary": "Inspect read-only CORS support", "tags": ["Health"], "responses": { "204": { "description": "CORS preflight response" } } }
    },
    "/api/forecast": {
      "get": {
        "operationId": "getPublicResetForecast",
        "summary": "Get the elapsed-aware public reset estimate",
        "description": "Returns a credential-free estimate for another broad-public full-refresh signal within 24 or 48 hours. It uses deduplicated, scope-filtered history, conditions on no reset being observed yet, and shrinks small at-risk samples toward a short-horizon baseline. It never forecasts a private account.",
        "tags": ["Forecast"],
        "responses": { "200": { "description": "Public reset forecast", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForecastResponse" } } } } }
      },
      "options": { "operationId": "getPublicResetForecastCors", "summary": "Inspect read-only CORS support", "tags": ["Forecast"], "responses": { "204": { "description": "CORS preflight response" } } }
    },
    "/api/status": {
      "get": {
        "operationId": "getPublicStatus",
        "summary": "Get the public timeline snapshot",
        "tags": ["Signals"],
        "responses": { "200": { "description": "Public timeline snapshot", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }
      }
    },
    "/feed.xml": {
      "get": {
        "operationId": "getEventFeed",
        "summary": "Get the public RSS event feed",
        "tags": ["Distribution"],
        "responses": { "200": { "description": "RSS feed", "content": { "application/rss+xml": { "schema": { "type": "string" } } } } }
      }
    },
    "/badge.svg": {
      "get": { "operationId": "getStatusBadge", "summary": "Get the embeddable status badge", "tags": ["Distribution"], "responses": { "200": { "description": "SVG badge", "content": { "image/svg+xml": { "schema": { "type": "string" } } } } } }
    },
    "/evidence-card.svg": {
      "get": { "operationId": "getEvidenceCard", "summary": "Get a shareable evidence card", "description": "Returns a readable SVG containing public timestamps, evidence state, scope, event ID, and a short integrity receipt. Use id to render a historical public event.", "tags": ["Distribution"], "parameters": [{ "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional public event ID." }], "responses": { "200": { "description": "SVG evidence card", "content": { "image/svg+xml": { "schema": { "type": "string" } } } }, "404": { "description": "Evidence card not found" } } }
    },
    "/resetpulse-client.mjs": {
      "get": { "operationId": "getResetPulseClient", "summary": "Get the one-file JavaScript integration client", "description": "Returns a credential-free ES module that fetches the verified packet, supports ETag revalidation, and verifies its SHA-256 receipt.", "tags": ["Distribution"], "responses": { "200": { "description": "JavaScript module", "content": { "application/javascript": { "schema": { "type": "string" } } } } } }
    },
    "/resetpulse-client.py": {
      "get": { "operationId": "getResetPulsePythonClient", "summary": "Get the zero-dependency Python integration client", "description": "Returns a credential-free Python standard-library client that fetches the verified packet, supports ETag revalidation, and verifies its SHA-256 receipt.", "tags": ["Distribution"], "responses": { "200": { "description": "Python module", "content": { "text/x-python": { "schema": { "type": "string" } } } } } }
    }
  },
  "components": {
    "headers": { "SignalVersion": { "description": "Canonical public-signal version shared by the compact packet, verified packet, and timeline; check before reprocessing.", "schema": { "type": "string", "example": "v1-abcdef12" } }, "SignalETag": { "description": "Strong validator for a compact or verified packet; send it as If-None-Match to avoid reprocessing unchanged evidence.", "schema": { "type": "string", "example": "\"v1-abcdef12\"" } }, "ResourceVersion": { "description": "Query-specific timeline response version; the timeline ETag is this value.", "schema": { "type": "string", "example": "v1-abcdef12" } }, "ResourceETag": { "description": "Strong validator for the exact timeline query and response; send it as If-None-Match for that query.", "schema": { "type": "string", "example": "\"v1-abcdef12\"" } } },
    "parameters": { "EventId": { "name": "id", "in": "path", "required": true, "description": "Public event ID from the packet or timeline.", "schema": { "type": "string", "pattern": "^event-[0-9]+$" } } },
    "schemas": {
      "PublicResetEvent": { "type": "object", "required": ["id", "publishedAt", "status", "confidence", "sourceRole", "claimScope", "eventType", "timingQuality", "links"], "properties": { "id": { "type": "string" }, "publishedAt": { "type": "string", "format": "date-time" }, "firstObservedAt": { "type": ["string", "null"], "format": "date-time" }, "confirmedAt": { "type": ["string", "null"], "format": "date-time" }, "status": { "type": "string", "enum": ["confirmed", "signal"] }, "confidence": { "type": "integer", "minimum": 0, "maximum": 100 }, "detectedSeconds": { "type": "integer", "minimum": 0 }, "sourceRole": { "type": "string" }, "claimScope": { "type": "string", "enum": ["broad-public", "plan-specific", "unknown"] }, "eventType": { "type": "string", "enum": ["full-refresh", "banked-credit", "announcement", "unknown"] }, "timingQuality": { "type": "string", "enum": ["measured", "historical", "migration-backfill", "external", "unknown"] }, "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } },
      "PublicSignalPacket": { "type": "object", "required": ["schema", "checkedAt", "freshness", "signalVersion", "primarySignal", "boundary", "links"], "properties": { "schema": { "const": "resetpulse.public-signal.v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "checkedAt": { "type": "string", "format": "date-time" }, "freshness": { "type": "object", "additionalProperties": true }, "signalVersion": { "type": "string" }, "primarySignal": { "$ref": "#/components/schemas/PublicResetEvent" }, "latestContext": { "anyOf": [{ "$ref": "#/components/schemas/PublicResetEvent" }, { "type": "null" }] }, "boundary": { "type": "object", "required": ["credentialsRequired", "privateAccountTelemetry"], "additionalProperties": true }, "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } },
      "Timeline": { "type": "object", "required": ["schema", "checkedAt", "freshness", "signalVersion", "resourceVersion", "query", "events", "boundary", "links"], "properties": { "schema": { "const": "resetpulse.timeline.v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "checkedAt": { "type": "string", "format": "date-time" }, "freshness": { "type": "object", "additionalProperties": true }, "signalVersion": { "type": "string", "description": "Canonical public-signal version shared with the compact and verified packets." }, "resourceVersion": { "type": "string", "description": "Query-specific response version used for ETag revalidation." }, "query": { "type": "object", "additionalProperties": true }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/PublicResetEvent" } }, "totalAvailable": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "boundary": { "type": "object", "required": ["credentialsRequired", "privateAccountTelemetry"], "additionalProperties": true }, "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } },
      "VerifiedPacket": { "type": "object", "required": ["schema", "checkedAt", "freshness", "signalVersion", "primarySignal", "latestContext", "receipt", "boundary", "links"], "properties": { "schema": { "const": "resetpulse.verified-packet.v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "checkedAt": { "type": "string", "format": "date-time" }, "freshness": { "type": "object", "additionalProperties": true }, "signalVersion": { "type": "string" }, "primarySignal": { "$ref": "#/components/schemas/PublicResetEvent" }, "latestContext": { "anyOf": [{ "$ref": "#/components/schemas/PublicResetEvent" }, { "type": "null" }] }, "receipt": { "type": "object", "required": ["schema", "schemaUrl", "value", "record"], "additionalProperties": true }, "boundary": { "type": "object", "required": ["credentialsRequired", "privateAccountTelemetry"], "additionalProperties": true }, "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } },
      "EvidenceReceipt": { "type": "object", "required": ["schema", "schemaUrl", "receipt", "record", "evidenceBoundary"], "properties": { "schema": { "const": "resetpulse.evidence.v1" }, "schemaUrl": { "type": "string", "format": "uri" }, "receipt": { "type": "string", "pattern": "^sha256:[0-9a-f]+$" }, "record": { "type": "object", "additionalProperties": true }, "evidenceBoundary": { "type": "object", "required": ["credentialsRequired", "personalAccountTelemetry"], "additionalProperties": true } } },
      "PropagationTrace": { "type": "object", "required": ["schema", "generatedAt", "event", "stages", "propagation", "boundary", "links"], "properties": { "schema": { "const": "resetpulse.propagation-trace.v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "event": { "type": "object", "additionalProperties": true }, "stages": { "type": "object", "additionalProperties": true }, "propagation": { "type": "object", "additionalProperties": true }, "boundary": { "type": "object", "additionalProperties": true }, "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } },
      "MonitorHealth": { "type": "object", "required": ["generatedAt", "monitor", "performance", "coverage", "evidenceBoundary"], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "monitor": { "type": "object", "additionalProperties": true }, "performance": { "type": "object", "additionalProperties": true }, "coverage": { "type": "object", "additionalProperties": true }, "evidenceBoundary": { "type": "string" } } },
      "PublicBenchmark": { "type": "object", "required": ["schema", "generatedAt", "method", "sources", "reconciliation", "forecastComparison", "boundary"], "properties": { "schema": { "const": "resetpulse.public-benchmark.v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "method": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "required": ["timingSummary"], "properties": { "timingSummary": { "type": "object", "required": ["sampleCount", "medianSeconds", "p95Seconds", "latestMeasuredAt", "basis"], "additionalProperties": true }, "forecast": { "type": "object", "required": ["probability24h", "probability48h", "confidence", "basis"], "additionalProperties": true } }, "additionalProperties": true } }, "reconciliation": { "type": "object", "required": ["state", "resetpulseStatus", "comparisonStatus", "comparedSourceCount", "agreeingSourceCount", "majorityStatus", "independenceStatus", "independenceNote", "note"], "additionalProperties": true }, "forecastComparison": { "type": "object", "required": ["sources", "probability24hRange", "probability48hRange", "note"], "properties": { "sources": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "probability24hRange": { "type": "object", "additionalProperties": true }, "probability48hRange": { "type": "object", "additionalProperties": true }, "note": { "type": "string" } }, "additionalProperties": true }, "boundary": { "type": "object", "additionalProperties": true } } }
      ,"ReliabilityReport": { "type": "object", "required": ["schema", "generatedAt", "collection", "window", "recordQuality", "timing", "integrity", "links"], "properties": { "schema": { "const": "resetpulse.reliability.v1" }, "generatedAt": { "type": "string", "format": "date-time" }, "collection": { "type": "object", "additionalProperties": true }, "window": { "type": "object", "additionalProperties": true }, "recordQuality": { "type": "object", "additionalProperties": true }, "timing": { "type": "object", "additionalProperties": true }, "integrity": { "type": "object", "required": ["credentialsRequired", "privateAccountTelemetry"], "additionalProperties": true }, "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } },
      "ForecastResponse": { "type": "object", "required": ["generatedAt", "scope", "accountSpecific", "forecast", "method", "limitations"], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "scope": { "const": "broad public reset signal" }, "accountSpecific": { "const": false }, "forecast": { "anyOf": [{ "$ref": "#/components/schemas/ResetForecast" }, { "type": "null" }] }, "method": { "type": "string" }, "limitations": { "type": "array", "items": { "type": "string" } } } },
      "ResetForecast": { "type": "object", "required": ["intervalCount", "eligibleEventCount", "excludedEventCount", "medianGapDays", "hoursSinceLatest", "atRiskCount", "probability24h", "probability48h", "backtest24h", "backtest48h", "brier24h", "brier48h", "backtestCount", "confidence", "method"], "properties": { "intervalCount": { "type": "integer", "minimum": 2 }, "eligibleEventCount": { "type": "integer", "minimum": 3 }, "excludedEventCount": { "type": "integer", "minimum": 0 }, "medianGapDays": { "type": "number", "minimum": 0 }, "hoursSinceLatest": { "type": "number", "minimum": 0 }, "atRiskCount": { "type": "integer", "minimum": 0 }, "probability24h": { "type": "integer", "minimum": 0, "maximum": 100 }, "probability48h": { "type": "integer", "minimum": 0, "maximum": 100 }, "backtest24h": { "type": ["integer", "null"], "minimum": 0, "maximum": 100 }, "backtest48h": { "type": ["integer", "null"], "minimum": 0, "maximum": 100 }, "brier24h": { "type": ["number", "null"], "minimum": 0, "maximum": 1 }, "brier48h": { "type": ["number", "null"], "minimum": 0, "maximum": 1 }, "backtestCount": { "type": "integer", "minimum": 0 }, "confidence": { "type": "string", "enum": ["low", "medium", "high"] }, "method": { "type": "string" } } }
    }
  }
}