API v1 · Getting started

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).

bash

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

Response (healthy)

http

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

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

Response (degraded)

http

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

{
  "status": "degraded",
  "version": "2026-08-10",
  "checks": {
    "db": { "ok": true, "latencyMs": 12 },
    "redis": { "ok": false, "latencyMs": 0 },
    "auditBuffer": { "ok": false, "depth": 0 }
  }
}

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`	Pending audit rows across all buffer shards.

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.

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.

bash

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

Response

http

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

{
  "status": "ok",
  "version": "2026-08-10",
  "principal": {
    "type": "api_key",
    "id": "key_01J9ZAB…"
  },
  "workspace": { "id": "org_2pYJfL3…" }
}

principal.type is "api_key" or "oauth_token" depending on the credential you presented; either way the object carries only type and id. The body is intentionally minimal — it's a canary, not an introspection endpoint. For scopes, plan and features, call /v1/workspaces/me.

This probe runs no dependency checks — it can only return 200 (or 401/429 on the credential itself). It proves your key works; it says nothing about whether the API is healthy. Wire /v1/health as your dependency probe, not this one: on a Redis outage /v1/health goes 503 while /v1/health/auth still answers 200. 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 — it takes the unauthenticated route branch, which skips auth, audit and the rate limiter entirely.

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	(no error envelope)	Public probe only — at least one downstream check failed. The body is the ordinary `{ status: "degraded", version, checks }` payload, not an `error` envelope, so switch on `status`. The auth probe never returns 503.

See errors/ for the full catalogue.