API Reference

Endpoints

Base URL https://your-domain/api/v1. All responses are JSON and carry an X-Request-Id header.

Authentication

Keyed endpoints accept the key in either header:

X-Api-Key: demo_pk_7f3a9c21e4b84d0f
# or
Authorization: Bearer demo_pk_7f3a9c21e4b84d0f

The demo key is limited to 30 requests/minute. Over the limit returns 429 with a Retry-After header.

GET /health

Liveness probe. No auth.

{
  "status": "ok",
  "service": "Statuslet",
  "version": "2.4.1",
  "uptime_seconds": 10432.5
}

GET /status

Per-component health. No auth.

{
  "status": "operational",
  "components": [
    { "name": "api", "status": "operational", "latency_ms": 12 },
    { "name": "database", "status": "operational", "latency_ms": 3 }
  ],
  "updated_at": 1766000000
}

POST /validate

Validate a JSON body. Requires a key. Body: { "email": "..." }.

# 200
{
  "valid": true,
  "normalized": { "email": "ada@example.com" },
  "token": "vt_1a2b3c4d5e6f7g8h9i0j1k2l",
  "expires_in": 3600
}
# 422
{ "error": { "code": "validation_failed",
             "message": "One or more fields are invalid.",
             "request_id": "req_..." } }

GET /echo

Returns your query string. Requires a key. Useful for debugging.

Error format

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry in 42s.",
    "request_id": "req_9f2c..."
  }
}