{ "openapi": "3.1.0", "info": { "title": "The Quantum Club — Status API", "version": "1.1.0", "summary": "Public, read-only status, uptime and incident data for The Quantum Club.", "description": "Public, read-only status + incident data for status.thequantumclub.com. All endpoints are unauthenticated and CORS-open (`Access-Control-Allow-Origin: *`). JSON GETs support conditional requests (`ETag` / `If-None-Match`, `Last-Modified` / `If-Modified-Since`) and return `304 Not Modified` when the cached copy is current.", "contact": { "name": "The Quantum Club", "url": "https://status.thequantumclub.com", "email": "support@thequantumclub.com" }, "license": { "name": "Proprietary", "url": "https://www.thequantumclub.com/legal/terms" } }, "servers": [ { "url": "https://status.thequantumclub.com", "description": "Production" } ], "security": [], "tags": [ { "name": "Status", "description": "Live status snapshot and rollup summary." }, { "name": "Incidents", "description": "Incident history, exports and feeds." }, { "name": "Integrations", "description": "Badges, embeds, metrics, calendars and webhooks." }, { "name": "Meta", "description": "Health, discovery and the OpenAPI document." } ], "components": { "schemas": { "ComponentStatus": { "type": "string", "description": "Health of a component or the overall system.", "enum": [ "operational", "degraded", "outage", "maintenance", "unknown" ], "examples": [ "operational" ] }, "UptimeDay": { "type": "object", "description": "One day of the 90-day uptime calendar.", "required": [ "day", "status", "uptimePct", "p50Ms", "p95Ms" ], "properties": { "day": { "type": "string", "format": "date", "examples": [ "2026-06-28" ] }, "status": { "$ref": "#/components/schemas/ComponentStatus" }, "uptimePct": { "type": "number", "description": "Uptime percentage 0–100; -1 means no data for the day.", "examples": [ 100 ] }, "p50Ms": { "type": [ "integer", "null" ], "examples": [ 180 ] }, "p95Ms": { "type": [ "integer", "null" ], "examples": [ 420 ] } } }, "Component": { "type": "object", "description": "Public-facing view of a single component.", "required": [ "id", "name", "status", "description", "source", "latestLatencyMs", "uptime90", "uptime7Pct", "uptime30Pct", "uptime90Pct" ], "properties": { "id": { "type": "string", "examples": [ "status-page" ] }, "name": { "type": "string", "examples": [ "Status Page" ] }, "status": { "$ref": "#/components/schemas/ComponentStatus" }, "description": { "type": "string", "examples": [ "Public status site" ] }, "source": { "type": "string", "enum": [ "probe", "federated" ], "description": "External Worker probe, or federated The Quantum Club SLOs." }, "latestLatencyMs": { "type": [ "integer", "null" ], "examples": [ 142 ] }, "uptime90": { "type": "array", "items": { "$ref": "#/components/schemas/UptimeDay" } }, "uptime7Pct": { "type": "number", "examples": [ 100 ] }, "uptime30Pct": { "type": "number", "examples": [ 99.98 ] }, "uptime90Pct": { "type": "number", "examples": [ 99.95 ] }, "regions": { "type": "object", "description": "Per-region status (regionHint → status), when multi-region.", "additionalProperties": { "$ref": "#/components/schemas/ComponentStatus" } } } }, "Group": { "type": "object", "description": "A named group of components.", "required": [ "id", "name", "components" ], "properties": { "id": { "type": "string", "examples": [ "platform" ] }, "name": { "type": "string", "examples": [ "Platform" ] }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/Component" } } } }, "Incident": { "type": "object", "description": "A single incident or scheduled-maintenance record.", "required": [ "id", "shortcode", "severity", "status", "title", "affectedComponents", "startedAt", "resolvedAt", "publicStatusMessage" ], "properties": { "id": { "type": "string", "examples": [ "inc_9f2a" ] }, "shortcode": { "type": "string", "examples": [ "INC-2026-014" ] }, "severity": { "type": "string", "enum": [ "P0", "P1", "P2", "P3" ], "description": "Severity, P0 (most severe) through P3." }, "status": { "type": "string", "enum": [ "open", "acknowledged", "investigating", "identified", "monitoring", "resolved" ] }, "title": { "type": "string", "examples": [ "Elevated API latency" ] }, "affectedComponents": { "type": "array", "items": { "type": "string" }, "examples": [ [ "api", "dashboard" ] ] }, "startedAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "publicStatusMessage": { "type": "string", "examples": [ "We are investigating elevated latency on the API." ] }, "kind": { "type": "string", "examples": [ "maintenance" ] }, "postmortemUrl": { "type": [ "string", "null" ], "format": "uri" }, "autoCreated": { "type": "boolean" } } }, "StatusSnapshot": { "type": "object", "description": "The unified status snapshot served by the page, API and feed.", "required": [ "schemaVersion", "brand", "overallStatus", "generatedAt", "stale", "groups", "activeIncidents", "recentIncidents", "scheduledMaintenance", "deployedVersion", "regions", "meta" ], "properties": { "schemaVersion": { "type": "integer", "examples": [ 3 ] }, "brand": { "type": "string", "examples": [ "The Quantum Club" ] }, "overallStatus": { "$ref": "#/components/schemas/ComponentStatus" }, "generatedAt": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean", "description": "True when served from a stale cache (backend unreachable)." }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "activeIncidents": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "recentIncidents": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "scheduledMaintenance": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "deployedVersion": { "type": [ "object", "null" ], "required": [ "label", "buildHash" ], "properties": { "label": { "type": "string", "examples": [ "v6afde788" ] }, "buildHash": { "type": "string", "examples": [ "6afde788" ] } } }, "regions": { "type": "array", "items": { "type": "object", "required": [ "hint", "name", "short" ], "properties": { "hint": { "type": "string", "examples": [ "weur" ] }, "name": { "type": "string", "examples": [ "Western Europe" ] }, "short": { "type": "string", "examples": [ "EU" ] } } } }, "meta": { "type": "object", "required": [ "federationOk", "probeOk", "cacheSeconds", "liveRegions" ], "properties": { "federationOk": { "type": "boolean" }, "probeOk": { "type": "boolean" }, "cacheSeconds": { "type": "integer", "examples": [ 30 ] }, "liveRegions": { "type": "array", "items": { "type": "string" } } } } } }, "Summary": { "type": "object", "description": "Compact rollup consumed by other properties for a status dot.", "required": [ "indicator", "description", "hasActiveIncident", "activeIncidentTitle", "activeIncidentShortcode", "generatedAt", "stale" ], "properties": { "indicator": { "type": "string", "enum": [ "none", "degraded", "outage", "maintenance" ], "description": "Headline indicator; `none` = all clear (fail-open)." }, "description": { "type": "string", "examples": [ "All systems operational" ] }, "hasActiveIncident": { "type": "boolean" }, "activeIncidentTitle": { "type": [ "string", "null" ] }, "activeIncidentShortcode": { "type": [ "string", "null" ] }, "generatedAt": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean" } } }, "IncidentsPage": { "type": "object", "description": "A page of incidents (active + recent), paginated.", "required": [ "total", "page", "per", "pages", "incidents" ], "properties": { "total": { "type": "integer", "examples": [ 42 ] }, "page": { "type": "integer", "minimum": 1, "examples": [ 1 ] }, "per": { "type": "integer", "minimum": 1, "maximum": 100, "examples": [ 25 ] }, "pages": { "type": "integer", "minimum": 1, "examples": [ 2 ] }, "incidents": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } } } }, "Error": { "type": "object", "description": "Standard error envelope.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "examples": [ "not_found" ] }, "message": { "type": "string", "examples": [ "No such endpoint." ] } } } } } }, "responses": { "NotFound": { "description": "The requested resource or endpoint does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "notFound": { "value": { "error": { "code": "not_found", "message": "No such endpoint." } } } } } } }, "RateLimited": { "description": "Too many requests — retry after the indicated delay.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 60 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rateLimited": { "value": { "error": { "code": "rate_limited", "message": "Too many requests." } } } } } } } } }, "paths": { "/api/v1/status": { "get": { "operationId": "getStatus", "tags": [ "Status" ], "summary": "Current status snapshot", "description": "The full unified status snapshot. Supports conditional GET — send `If-None-Match` or `If-Modified-Since` to receive `304 Not Modified` when unchanged.", "parameters": [ { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Weak ETag from a prior response, e.g. `W/\"2026-06-28T12:00:00.000Z\"`." }, { "name": "If-Modified-Since", "in": "header", "required": false, "schema": { "type": "string" }, "description": "HTTP-date; `304` when at/after the snapshot `generatedAt`." } ], "responses": { "200": { "description": "Status snapshot.", "headers": { "ETag": { "schema": { "type": "string" }, "description": "Weak validator." }, "Last-Modified": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusSnapshot" } } } }, "304": { "description": "Not modified — cached copy is current." } } } }, "/api/v1/status/summary": { "get": { "operationId": "getStatusSummary", "tags": [ "Status" ], "summary": "Compact status rollup", "description": "Small rollup with a single indicator and the top active incident. Designed for other properties to render a status dot. Supports conditional GET.", "responses": { "200": { "description": "Status summary.", "headers": { "ETag": { "schema": { "type": "string" } }, "Last-Modified": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Summary" } } } }, "304": { "description": "Not modified — cached copy is current." } } } }, "/api/v1/incidents": { "get": { "operationId": "listIncidents", "tags": [ "Incidents" ], "summary": "Paginated incidents", "description": "Active + recent incidents, paginated and optionally filtered by component.", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "component", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter to incidents affecting this component id." } ], "responses": { "200": { "description": "A page of incidents.", "headers": { "ETag": { "schema": { "type": "string" } }, "Last-Modified": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentsPage" } } } }, "304": { "description": "Not modified — cached copy is current." } } } }, "/api/v1/incidents.csv": { "get": { "operationId": "exportIncidentsCsv", "tags": [ "Incidents" ], "summary": "Incident history as CSV", "description": "Active + recent incidents as a downloadable CSV.", "responses": { "200": { "description": "CSV export.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" }, "examples": { "csv": { "value": "shortcode,severity,status,title,affected_components,started_at,resolved_at\r\n\"INC-2026-014\",\"P2\",\"resolved\",\"Elevated API latency\",\"api\",\"2026-06-28T10:00:00.000Z\",\"2026-06-28T10:45:00.000Z\"" } } } } } } } }, "/api/v1/uptime.csv": { "get": { "operationId": "exportUptimeCsv", "tags": [ "Incidents" ], "summary": "Per-component 90-day uptime as CSV", "description": "The 90-day uptime calendar for every component as a downloadable CSV.", "responses": { "200": { "description": "CSV export.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" }, "examples": { "csv": { "value": "component,day,status,uptime_pct,p50_ms,p95_ms\r\n\"status-page\",\"2026-06-28\",\"operational\",\"100\",\"180\",\"420\"" } } } } } } } }, "/api/health": { "get": { "operationId": "getHealth", "tags": [ "Meta" ], "summary": "Dead-man health check", "description": "Returns `200` when the snapshot is fresh, `503` when stale.", "responses": { "200": { "description": "Healthy — snapshot is fresh.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "examples": [ true ] }, "generatedAt": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean", "examples": [ false ] } } }, "examples": { "healthy": { "value": { "ok": true, "stale": false } } } } } }, "503": { "description": "Stale — snapshot is older than the freshness budget.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "examples": [ false ] }, "stale": { "type": "boolean", "examples": [ true ] } } }, "examples": { "stale": { "value": { "ok": false, "stale": true } } } } } } } } }, "/api/openapi.json": { "get": { "operationId": "getOpenApi", "tags": [ "Meta" ], "summary": "OpenAPI 3.1 document", "description": "This document — a machine-readable description of the Status API.", "responses": { "200": { "description": "The OpenAPI 3.1 document.", "content": { "application/json": { "schema": { "type": "object", "description": "An OpenAPI 3.1 document.", "additionalProperties": true } } } } } } }, "/feed.xml": { "get": { "operationId": "getIncidentFeed", "tags": [ "Incidents" ], "summary": "RSS incident feed", "description": "RSS 2.0 feed of incidents, optionally filtered to a single component.", "parameters": [ { "name": "component", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter the feed to incidents affecting this component id." } ], "responses": { "200": { "description": "RSS 2.0 feed.", "content": { "application/rss+xml": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/maintenance.ics": { "get": { "operationId": "getMaintenanceCalendar", "tags": [ "Integrations" ], "summary": "Scheduled-maintenance calendar", "description": "iCal (text/calendar) subscription of scheduled maintenance windows.", "responses": { "200": { "description": "iCalendar document.", "content": { "text/calendar": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/metrics": { "get": { "operationId": "getMetrics", "tags": [ "Integrations" ], "summary": "Prometheus/OpenMetrics exposition", "description": "Status and uptime as OpenMetrics text for Prometheus scraping.", "responses": { "200": { "description": "OpenMetrics exposition.", "content": { "text/plain": { "schema": { "type": "string", "format": "binary" }, "examples": { "metrics": { "value": "# HELP status_component_up Component health (1=up).\n# TYPE status_component_up gauge\nstatus_component_up{component=\"status-page\"} 1" } } } } } } } }, "/badge.svg": { "get": { "operationId": "getBadge", "tags": [ "Integrations" ], "summary": "Status badge (SVG)", "description": "An SVG status badge for overall status, or a single component.", "parameters": [ { "name": "component", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Render the badge for this component id instead of overall status." } ], "responses": { "200": { "description": "SVG badge.", "content": { "image/svg+xml": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/embed": { "get": { "operationId": "getEmbed", "tags": [ "Integrations" ], "summary": "Embeddable status widget", "description": "An embeddable HTML status widget, optionally scoped to components.", "parameters": [ { "name": "components", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated component ids to scope the widget to." } ], "responses": { "200": { "description": "HTML widget.", "content": { "text/html": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/api/v1/webhooks": { "post": { "operationId": "subscribeWebhook", "tags": [ "Integrations" ], "summary": "Subscribe a webhook", "description": "Subscribe a Slack or Discord incoming-webhook URL to status-change notifications.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Slack or Discord incoming-webhook URL." }, "components": { "type": "array", "items": { "type": "string" }, "description": "Optional component-id filter. Omit/empty = subscribe to overall-headline changes." } } }, "examples": { "slack": { "value": { "url": "https://hooks.slack.com/services/T000/B000/XXXX", "components": [ "api" ] } } } } } }, "responses": { "201": { "description": "Webhook registered.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "examples": [ "wh_4f8a2c" ] }, "url": { "type": "string", "format": "uri" }, "components": { "type": "array", "items": { "type": "string" } } } }, "examples": { "created": { "value": { "id": "wh_4f8a2c", "components": [ "api" ] } } } } } }, "422": { "description": "Unsupported or malformed webhook URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid": { "value": { "error": { "code": "unsupported_webhook", "message": "Only Slack or Discord webhook URLs are accepted." } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "unsubscribeWebhook", "tags": [ "Integrations" ], "summary": "Unsubscribe a webhook", "description": "Remove a previously registered webhook by its id.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The webhook id returned at subscription time." } ], "responses": { "200": { "description": "Webhook removed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "examples": [ true ] } } }, "examples": { "removed": { "value": { "ok": true } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } } } }