Status APIs

Relevant source files

The following files were used as context for generating this wiki page:

• apps/web/src/pages/api/status.json.ts
• apps/web/src/lib/api.ts
• ARCHITECTURE.md
• README.md
• packages/core/src/badge.ts
• packages/core/src/types.ts
• apps/web/src/lib/data.ts

StatusBeam provides a comprehensive suite of public JSON APIs and badge endpoints served directly from the network edge. These APIs allow users and third-party services to programmatically access the current state of monitored services, historical uptime data, and response-time metrics without hitting client-side rate limits.

The Status APIs are designed to be highly resilient, running entirely on Cloudflare edge primitives. They serve data from a pre-aggregated snapshot stored in Cloudflare KV, ensuring that the status page and its APIs can survive outages in the very services they are monitoring.

Sources: README.md:14-25, ARCHITECTURE.md:14-25

Architecture and Data Flow

The Status APIs follow a "read-only consumer" pattern. Data is produced by a background Cron Worker that probes services and writes snapshots to Cloudflare KV. The API layer, hosted within the Astro application, simply reads these snapshots and serves them with appropriate caching headers.

Edge Caching and Invalidation

To ensure high performance and low latency, the Status APIs utilize Cloudflare Workers Cache. API responses include Cache-Control and Cache-Tag headers. When the Cron Worker detects a status change, it purges the edge cache by tag, allowing for near-instant updates across all API consumers.

Sources: ARCHITECTURE.md:105-115, README.md:65-75

Public API Endpoints

StatusBeam exposes two primary categories of programmatic interfaces: the Status JSON API for structured data and Badge APIs for visual status indicators.

Status JSON API

The JSON API provides the full state of the dashboard or specific service records. These endpoints include Access-Control-Allow-Origin: * headers to permit direct browser-based integration.

Endpoint	Description
GET /api/status.json	Returns the entire dashboard summary, including rolled-up status and per-site metrics (status, response time, uptime).
GET /api/status/<slug>.json	Returns the full record for a specific site, including 90-day history and response-time samples.

Sources: README.md:214-221, apps/web/src/pages/api/status.json.ts

Badge APIs (Shields.io Compatible)

StatusBeam implements the shields.io endpoint protocol. Instead of generating images directly, StatusBeam serves a JSON contract that shields.io uses to render SVG badges.

Badge Type	Endpoint Path	Default Period
Overall Status	/api/badge.json	N/A
Site Status	/api/badge/<slug>.json	N/A
Site Uptime	/api/badge/<slug>/uptime.json	month (options: day, week, month)
Response Time	/api/badge/<slug>/response-time.json	N/A

Sources: README.md:195-212, packages/core/src/badge.ts

Data Models

The API responses are derived from shared domain models defined in the core package.

Site Summary Snapshot

The KV summary key contains an array of SiteSummary objects. This is the primary data source for the /api/status.json endpoint.

export interface SiteSummary {
  slug: string;
  name: string;
  status: CheckStatus;
  responseTime: number;
  lastChecked: string;
  uptime: {
    day: number;
    week: number;
    month: number;
  };
}

Sources: ARCHITECTURE.md:95-103, packages/core/src/types.ts

Badge Response Schema

The badge endpoints return a JSON structure compatible with the Shields.io endpoint specification.

{
  "schemaVersion": 1,
  "label": "status",
  "message": "operational",
  "color": "brightgreen"
}

Example JSON output for a status badge.

Sources: packages/core/src/badge.ts, README.md:209-212

API Implementation Details

The APIs are implemented as Astro API routes that interface with the project's internal data library.

Implementation Reference

• KV Reads: The loadSummary function in apps/web/src/lib/data.ts handles the retrieval and parsing of the snapshot from KV.
• Cache Tags: The STATUS_PAGE_TAG and site-specific status-site-<slug> tags are emitted as headers to enable granular cache invalidation.
• Badge Logic: The mapping of severity levels (green, yellow, red) to Shields.io colors is handled by packages/core/src/badge.ts.

Sources: ARCHITECTURE.md:129-132, apps/web/src/lib/data.ts, apps/web/src/lib/api.ts

Summary

StatusBeam's Status APIs provide a robust, edge-native way to consume service health data. By separating the check logic from the display/API layer and using Cloudflare KV as a high-speed cache, the system ensures that status information remains available even during significant infrastructure failures. Programmatic access via JSON and Shields.io-compatible badges makes it easy to integrate service status into external documentation, READMEs, and monitoring dashboards.