Health

Lightweight liveness probe scoped to the authenticated workspace. Confirms the API is reachable, your key is valid, and returns your workspace identity and plan.

Use this when

Smoke-testing a new API key before wiring it into your app.
Confirming which workspace and plan a key belongs to.
Powering an external uptime monitor or readiness check in CI.

Method	GET
Path	`/api/v1/health`
Auth	Bearer
Credits	0

Request

No body. No query parameters.

Response

Field	Type	Description
`status`	`string`	Always `"healthy"` when the endpoint returns 200.
`workspace_id`	`uuid`	ID of the workspace owning the API key used on this request.
`plan_name`	`string`	Plan identifier for the workspace (e.g. `"free"`).
`retrieval`	`object`	Retrieval-path health, separate from API liveness. See below.

`retrieval`

Field	Type	Description
`status`	`string`	`"healthy"`, `"degraded"`, or `"unknown"`. Degraded when the browser tier is unreachable or more than 25% of your recent calls errored.
`renderer.status`	`string`	`"up"`, `"down"`, `"disabled"`, or `"unknown"` — reachability of the headless-browser worker used for JS-heavy and soft-blocked pages.
`renderer.latencyMs`	`number \| null`	Probe round-trip in milliseconds.
`recentErrorRate`	`number \| null`	0–1 share of your workspace's calls that errored in the window. `null` when there is no traffic to measure.
`recentSampleSize`	`number`	Calls counted in the window.
`windowMinutes`	`number`	Length of the error-rate window (15).

Poll this to fail over to a secondary retrieval path early rather than absorbing full timeouts.

Example response

{
  "ok": true,
  "data": {
    "status": "healthy",
    "workspace_id": "8f3a1c20-9b4e-4d77-bc1e-3e5a7d2c9f10",
    "plan_name": "free",
    "retrieval": {
      "status": "healthy",
      "renderer": { "status": "up", "latencyMs": 142 },
      "recentErrorRate": 0.04,
      "recentSampleSize": 96,
      "windowMinutes": 15
    }
  }
}

Example

curl https://www.gyrence.com/api/v1/health \
  -H "Authorization: Bearer $GYRENCE_API_KEY"

Errors

Code	Type	Description
`unauthorized`	`401`	Missing or invalid `Authorization: Bearer <key>` header.
`unavailable`	`503`	"health check unavailable" — the workspace plan lookup (`get_plan_name` RPC) failed. Retry with backoff.

Credits

0 credits per call regardless of frequency. Calls are still recorded in usage_events for audit.

What this does NOT check

A 200 with status: "healthy" confirms the Gyrence API, your API key, and the workspace plan lookup are alive, and — via retrieval — whether the headless-browser worker is reachable and how often your recent calls errored. It still does not probe Brave Search or the AI Gateway directly, so Search and Extract can degrade without moving retrieval.status.

Unauthenticated probe

For a public liveness check (no API key, no workspace context), call GET /api/public/health. Unlike the authenticated endpoint, the response is not wrapped in the standard envelope:

{
  "status": "ok",
  "timestamp": "2026-05-30T18:42:00.000Z",
  "uptime": 1284.31
}

Use this when you can't safely embed an API key (e.g. status-page pingers).