Public API

/api/v1 is the stable read-only interface for alternate frontends, public panels, Canvas themes, and server-side integrations. Reading needs no token; write access is not exposed. This documentation matches Worker 1.1.93; the manifest of the target deployment is authoritative.

Endpoints

Method	Path	Purpose	Default rate limit
GET	/api/v1	version, capabilities, endpoint discovery	public policy
GET	/api/v1/manifest	alias of the manifest	public policy
GET	/api/v1/status	targets, current state, summaries, telemetry	120/min/IP
GET	/api/v1/checks	availability history of one target	120/min/IP
GET	/api/v1/metrics	metric history of one agent	30/min/IP
GET	/api/v1/pings	Agent TCP ping history	30/min/IP
GET	/api/v1/latency	external latency history	60/min/IP

Limits are production defaults and may change; clients should not treat them as concurrency targets. A status page only needs to refresh per cache period.

All routes are also covered by best-effort global rate limiting. If the counter is unavailable, public reads may keep serving; clients should still back off on 429 and never assume a request was not limited.

Basic requests

export API_BASE='https://YOUR-API'
curl -fsSL "$API_BASE/api/v1"
curl -fsSL "$API_BASE/api/v1/status?days=30&lite=1"

const response = await fetch(`${apiBase}/api/v1/status?days=30&lite=1`, {
  method: 'GET',
  credentials: 'omit',
  headers: { accept: 'application/json' },
})

if (!response.ok) throw new Error(`HTTP ${response.status}`)
const status = await response.json()

CORS

Server-side integration is not affected by browser CORS. Browser frontends must add their exact origin to DEVELOPER_API_ORIGINS:

DEVELOPER_API_ORIGINS = "https://status.example.com,http://localhost:5173"

Rules: full origins only, no paths or trailing slashes; HTTPS for production; HTTP only for localhost dev addresses; * is ignored; the variable affects only /api/v1, never admin or Agent write endpoints. The Worker's own configured site origin is added automatically. On a miss, the response may still be HTTP 200 but Access-Control-Allow-Origin will not echo the request origin, so browsers block script reads.

Response conventions

Success responses include ok: true; errors usually include ok: false and error. Clients must check both the HTTP status and JSON ok (latency compat errors may use HTTP 200). v1 responses carry X-NIE-SLA-API-Version: v1 and retain the legacy X-NStatus-API-Version alias. Cache/source headers follow the same X-NIE-SLA-* primary plus X-NStatus-* v1 compatibility pattern; they do not change semantics.

Caching and refresh

Endpoints may return Cache-Control, and status/history may hit the Cloudflare Cache API. Respect cache headers; do not poll to generate meaningless traffic. Recommended for public panels: refresh current state every 20-60 s; request charts only when details open or the range changes; pause polling when hidden; add random delay after network recovery.

Stability rules

Within v1 the server may add optional fields, array members, and capability flags, but will not silently delete or rename existing fields. Clients must ignore unknown fields and handle null, empty arrays, missing history, and temporarily stale sources.

Error policy: Error Handling. Reusable client, polling, state model, and chart advice: API Integration.