Health

GET /v1/health is an unauthenticated liveness probe. Use it for uptime checks and to read the API’s current schema version. It has two modes: a cheap shallow check by default, and a deep dependency probe with ?probe=deep.

No Authorization header required. (The discovery endpoints GET /v1/surfaces and GET /v1/regions are also public; everything else needs a key.)

Shallow check (default)

The default check confirms the Worker is running and its storage bindings are wired. It does not touch the dependencies — it’s cheap enough to hit on a tight interval.

curl https://api.aisearchapi.dev/v1/health

const res = await fetch('https://api.aisearchapi.dev/v1/health');
const health = await res.json();
console.log(health.status); // "ok"

import requests

res = requests.get("https://api.aisearchapi.dev/v1/health")
print(res.json()["status"])  # "ok"

200 OK

{
  "status": "ok",
  "schemaVersion": "2026-06-27",
  "bindings": { "artifacts": true, "edgeCache": true, "hyperdrive": true }
}

status

string

Liveness indicator: ok or degraded. On the shallow check, ok means every binding is present; a missing binding is degraded with HTTP 503.

schemaVersion

string

The current envelope/response schema version (a date string, e.g. 2026-06-27). This same value is returned as the X-AISearch-Version header on every response, so you can pin or detect schema changes without calling this endpoint.

bindings

object

Whether the API’s storage bindings are wired: artifacts (durable artifact store), edgeCache, and hyperdrive (database connectivity). All true in a healthy deployment.

Deep probe (`?probe=deep`)

Add ?probe=deep to run a live round-trip against every critical dependency — a SELECT 1 over Hyperdrive→Postgres, a SELECT 1 over D1 (edgeCache), and an R2 list (artifacts) — each under a hard ~2-second timeout. The response shape is identical, but each bindings boolean now reflects a real round-trip, not just binding presence. If any dependency fails or times out, status flips to degraded and the HTTP code becomes 503.

curl -i "https://api.aisearchapi.dev/v1/health?probe=deep"

const res = await fetch('https://api.aisearchapi.dev/v1/health?probe=deep');
const health = await res.json();
console.log(res.status, health.status); // 200 "ok"  — or  503 "degraded"

import requests

res = requests.get("https://api.aisearchapi.dev/v1/health?probe=deep")
print(res.status_code, res.json()["status"])  # 200 "ok" or 503 "degraded"

503 Service Unavailable (a dependency is down)

{
  "status": "degraded",
  "schemaVersion": "2026-06-27",
  "bindings": { "artifacts": true, "edgeCache": true, "hyperdrive": false }
}

Point production uptime monitors at ?probe=deep, not the shallow check. The shallow check can report ok while Postgres is unreachable — it only verifies the binding exists. The deep probe actually exercises each dependency, so a 200 with status: "ok" from it means the API can genuinely serve work. Alert on any 503 or status: "degraded".

Deep-probe results are cached briefly in-process, so a burst of monitor hits (or a retry storm) can’t pile up dependency connections. Because it takes no auth, you can probe it from anywhere without exposing your API key.

Endpoints

Account & discovery

Watches

By surface

Shallow check (default)

Deep probe (`?probe=deep`)

​Shallow check (default)

​Deep probe (?probe=deep)

Shallow check (default)

Deep probe (`?probe=deep`)