Health

Two health endpoints ship in v1: an unauthenticated liveness probe and an authenticated canary probe. Both return a small JSON body suitable for direct consumption by uptime checkers and your own deployment smoke tests.

`GET /v1/health` — public liveness probe

Unauthenticated. No Authorization header is required (and any header you send is ignored).

curl -i https://api.scripe.io/v1/health

Response (healthy)

HTTP/1.1 200 OK
Cache-Control: max-age=5, public
Content-Type: application/json

{
  "status": "ok",
  "version": "2026-08-01",
  "checks": {
    "db": { "ok": true, "latencyMs": 9 },
    "redis": { "ok": true, "latencyMs": 3 },
    "auditBuffer": { "ok": true, "depth": 14 }
  }
}

Response (degraded)

HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
  "status": "degraded",
  "version": "2026-08-01",
  "checks": {
    "db": { "ok": true, "latencyMs": 12 },
    "redis": { "ok": false, "latencyMs": 0, "error": "ECONNREFUSED" },
    "auditBuffer": { "ok": false, "depth": null, "error": "redis_unavailable" }
  }
}

Semantics

Field	Meaning
`status`	`"ok"` or `"degraded"`. Switch on this rather than HTTP status.
`version`	The API version this instance currently advertises as default.
`checks.db.ok`	DB connectivity. `false` is a hard outage; the read API will fail.
`checks.redis.ok`	Redis connectivity. `false` degrades rate limiting + audit buffering.
`checks.auditBuffer.ok`	Whether the audit-write queue can accept rows.
`checks.auditBuffer.depth`	Combined LLEN across all 16 shards. Useful for SRE dashboards.

We return HTTP 503 when status === "degraded" so naive uptime checkers correctly mark the service unhealthy. The response is cached at the edge for 5 seconds (Cache-Control: max-age=5, public). Don’t rely on this probe for sub-second observability; use the Sentry / Datadog spans for that.

When to use

Container readiness probes. Kubernetes / Vercel-style checks.
External uptime monitors. Pingdom, BetterUptime, etc.
Pre-deploy smoke tests. Block a deploy if the canary returns 503.

When NOT to use

Per-request latency tracking. Cached for 5 s; the latency you see is bounded by the cache, not by the API.
Authenticated canary checks. Use /v1/health/auth instead — that one exercises the auth path too.

`GET /v1/health/auth` — authenticated canary

Same shape, but the request must carry a valid Authorization header. Use this after a deploy to confirm both the unauth surface AND the API key path are healthy from your client’s perspective.

curl -i https://api.scripe.io/v1/health/auth \
  -H "Authorization: Bearer scripe_sk_live_…" \
  -H "Scripe-Api-Version: 2026-08-01"

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ok",
  "version": "2026-08-01",
  "principal": {
    "type": "api_key",
    "id": "key_01J9ZAB…",
    "scopes": ["notes:read", "posts:read"]
  },
  "workspace": { "id": "org_2pYJfL3…" }
}

The body is intentionally minimal — it’s a canary, not an introspection endpoint. For the full workspace + plan + features payload, call /v1/workspaces/me. A 503 here means the same downstream subsystems used by the public probe are unhealthy. A 401 here means the key is bad — investigate that before you investigate the API.

Counted against the rate limit?

Yes — /v1/health/auth consumes from the workspace’s read bucket so a broken canary loop can’t bypass quota. The unauthenticated /v1/health does not count, and is rate-limited only at the IP layer.

Errors

Status	Code	When
200	(none)	All checks healthy.
401	`unauthenticated`, `invalid_token`, `key_revoked`, `key_expired`	Auth probe only.
429	`rate_limited`	Auth probe only — workspace quota burned.
503	`service_unavailable`	At least one downstream check failed.

See errors/ for the full catalogue.

Documentation Index

​Health

​GET /v1/health — public liveness probe

​Response (healthy)

​Response (degraded)

​Semantics

​When to use

​When NOT to use

​GET /v1/health/auth — authenticated canary

​Response

​Counted against the rate limit?

​Errors