Service Health

GET /v1/health tells you which Chab tools can start work right now. It is public, needs no API key and does not use credits, so an agent can call it before a batch of work or after an error.

curl https://www.chab.ai/v1/health

{
  "data": {
    "service": "chab-api",
    "api_version": "v1",
    "status": "degraded",
    "updated_at": "2026-10-29T12:00:00Z",
    "families": [
      {"family": "research", "state": "degraded", "covered_operation_keys": [], "remediation": "/docs/reference/service-health.html"},
      {"family": "search", "state": "healthy", "covered_operation_keys": ["search.web", "search.serp"], "remediation": null}
    ],
    "free_mode": {"state": "enabled"}
  }
}

The response comes in the normal success envelope and is cached for about 30 seconds.

What the response means

status is ok when every one of the 19 public tools can start, and degraded when at least one cannot. Connected Mail and Drive families are listed too, but they do not change the overall status.
updated_at is when the status was worked out.
families has one entry per tool family (search, seo, business, contacts, scrape, screenshots, convert, llm, translate, research and the connected-data families).
covered_operation_keys lists exactly the operations in that family that can start now. It is an empty list when none can. Check this list rather than the family state when you care about one operation: a family can be healthy while one of its operations is switched off or has no ready provider.
remediation links back to this page when the family is not healthy.

Each family has one of these states:

State	Meaning
`healthy`	At least one operation in the family can start. `covered_operation_keys` says which.
`degraded`	New starts are paused for a short while, either because recent requests to the family failed too often or because Chab paused it.
`disabled`	Chab has switched the family off.
`unknown`	No provider is ready for any operation in the family right now.

free_mode.state says whether free credits (the guest trial and the signup bonus) can start work:

State	Meaning
`enabled`	Free credits can be used.
`degraded`	Free credits are paused for a while, for example because the daily free-use limit has been reached. Paid credits are not affected.
`disabled`	Free credits cannot be used right now.

free_mode is not a balance. Free credits are one-off grants and do not refresh. Read your own balance with GET /v1/credits; see Free credits and limits.

Operation starts

Every start goes through the same checks, whether it comes from the REST API, the CLI, hosted MCP or the browser trial. An operation starts when:

its tool is switched on and not paused by Chab,
its family is not paused after a run of failures,
a provider is ready to serve it, and
you have enough credits for it. Free credits also need room under the daily free-use limit.

When one of the first three checks fails, the start is refused with one of these errors. A refused start is never billed, and its idempotency key is released, so you can retry later with the same key and body.

Code	HTTP	Retry	What it means	What to do
`operation_family_degraded`	503	Yes	The family is paused for a short while. Chab pauses a family automatically when too many recent requests to it fail, and opens it again by itself after a few minutes without new failures. Chab can also pause a family or one operation by hand.	Wait for `Retry-After` (30 seconds), check `/v1/health`, then retry the same request.
`operation_family_disabled`	503	No	Chab has switched this family or operation off.	Do not retry in a loop. Use another tool, or check `/v1/health` later and retry once the operation appears in `covered_operation_keys` again.
`provider_unavailable`	503	Yes	No provider is ready to serve this operation right now. Other tools keep working.	Wait for `Retry-After`, then retry with the same idempotency key.

operation_family_degraded and operation_family_disabled include error.details.family and error.details.remediation:

{
  "error": {
    "code": "operation_family_degraded",
    "message": "This operation family is temporarily degraded.",
    "retryable": true,
    "details": {
      "family": "research",
      "remediation": "/docs/reference/service-health.html"
    }
  },
  "request_id": "req_123"
}

When free credits pause because the daily free-use limit is reached, a free start returns promotional_budget_exhausted (503, retryable, may include Retry-After). Try again later; paid credits keep working. See Free-mode operation errors.

Operations that were already accepted are not affected by any of this: you can still poll them, read their results and receive their callbacks.

Tips for agents and scripts

Check covered_operation_keys before starting a long batch, and pick another tool when the one you need is missing.
Retry operation_family_degraded and provider_unavailable after Retry-After with the same idempotency key and body. Stop and tell the person after a few failed tries.
Treat operation_family_disabled as a stop, not a retry.
A healthy family is not a promise that a particular request will succeed. Handle per-request errors as described in Errors, Rate Limits, and Pagination.

The health response leaves out provider names, capacity, thresholds and internal incident details.