Foundation Endpoints

These endpoints are callable in the current /v1 foundation release. They are intended for setup checks, authentication checks, error catalog discovery, and idempotency smoke tests.

Foundation endpoints are non-billable and do not require a paid plan. They are callable regardless of subscription state when their authentication and scope requirements are satisfied.

GET/v1/health

Public health check. No API key is required.

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

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

status is ok when every public tool can start right now, otherwise degraded. Each family has a state (healthy, degraded, disabled, or unknown) and covered_operation_keys, the exact operations in that family that can start now (an empty list when none can). free_mode.state is disabled, enabled, or degraded and tells you whether free credits can start work at the moment. It is not a balance or a monthly refresh signal; free promotional credits are one-off grants and do not refresh monthly. The response is cached for about 30 seconds. See Service Health for family states and safe retry behavior.

GET/v1/me

Returns the authenticated team API key or guest trial credential context. Requires an Authorization: Bearer ... token; no operation scope is required.

curl https://www.chab.ai/v1/me \
  -H "Authorization: Bearer CHAB_API_KEY"

{
  "data": {
    "principal_type": "team_api_token",
    "team_id": 123,
    "token_id": "456",
    "token_public_id": "870b679b-210c-4d33-9d2c-a5b091693f42",
    "scopes": [
      "api:examples:write"
    ],
    "token_controls": {
      "policy_revision": 3,
      "feature_access": {"mode": "selected", "snapshot_stale": false},
      "ip_restrictions": {"restricted": true, "allow_rule_count": 1, "deny_rule_count": 0},
      "spending": {"mode": "capped", "active_reserved_credits": 5, "allowance": {"version": 1, "limit_credits": 100, "settled_credits": 20, "held_credits": 5, "remaining_credits": 75}},
      "project_access": {"mode": "selected", "selected_project_ids": [42], "selected_count": 1}
    },
    "request_id": "req_123"
  },
  "meta": {
    "request_id": "req_123"
  }
}

Guest trial API credentials return a guest-scoped shape instead of team token controls. The free_access.free_credit_policy.monthly_refresh value is always false; free promotional credits are one-off grants and do not refresh monthly.

{
  "data": {
    "principal_type": "guest_trial",
    "team_id": null,
    "guest_id": "gst_01JZ7H0A1B2C3D4E5F6G7H8J9K",
    "principal_id": "guest_trial:gtp_01JZ7H0A1B2C3D4E5F6G7H8J",
    "scopes": ["api:credits:read", "api:search:read"],
    "credential": {
      "id": "gtc_01JZ7H0A1B2C3D4E5F6G7H8J",
      "transport": "api_cli",
      "expires_at": "2026-09-16T10:00:00+00:00"
    },
    "free_access": {
      "guest": {
        "id": "gst_01JZ7H0A1B2C3D4E5F6G7H8J9K",
        "status": "active",
        "expires_at": "2026-09-16T10:00:00+00:00"
      },
      "free_credit_policy": {
        "grant_model": "one_off_promotional_lot",
        "monthly_refresh": false,
        "description": "Free promotional credits are one-off grants and do not refresh monthly."
      }
    },
    "request_id": "req_123"
  }
}

GET/v1/errors

Public machine-readable error catalog. No API key is required.

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

Each entry includes the error code, HTTP status, retryability, chargeability, safe-to-show flag, message, user action, docs URL, and emitting surface.

POST/v1/signup

For agents on a free guest trial key. Send the email address the person gave you (never guess it). Chab emails them a link; when they confirm, a free account is created (or they sign in to their existing one), the trial credits left and the operation history move into it, and new accounts get bonus credits. The guest key then stops working: sign in again with chab login, or start a device sign-in with client_id=chab-agent (see CLI device sign-in) and give the person the verification link.

curl -X POST https://www.chab.ai/v1/signup \
  -H "Authorization: Bearer CHAB_GUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

Returns 202 Accepted with data.sent, data.email, data.expires_in_hours, data.message (what to tell the person), data.after_confirmation and data.reconnect (how to sign in again). The answer is the same whether or not the address already has an account. Sending is limited to a few emails per hour for each guest and each address (rate_limited). A team API key gets resource_state_conflict: it already belongs to an account.

POST/v1/examples/echo

Non-billable setup endpoint. Requires a team API key with api:examples:write and an Idempotency-Key.

curl -X POST https://www.chab.ai/v1/examples/echo \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: setup-echo-001" \
  -d '{"data":{"hello":"world"}}'

{
  "data": {
    "echo": {
      "hello": "world"
    }
  },
  "meta": {
    "request_id": "req_123"
  }
}

To create a real non-billable operation for setup polling, send simulate_async=true:

curl -X POST https://www.chab.ai/v1/examples/echo \
  -H "Authorization: Bearer CHAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: setup-echo-async-001" \
  -d '{"simulate_async":true,"callback_url":"https://example.com/chab-callback","callback_secret":"replace-with-a-long-random-secret","callback_events":["operation.succeeded"],"data":{"hello":"world"}}'

callback_url, callback_secret, callback_events, and callback_notify_on_expiration are optional. When provided, they request a one-off operation callback as documented in Webhooks. callback_url must be HTTPS and publicly reachable, and callback_secret is required with it.

{
  "operation": {
    "id": "op_01JZ7H0A1B2C3D4E5F6G7H8J9K",
    "status": "queued",
    "operation_key": "examples.echo",
    "family": "examples",
    "status_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K",
    "result_url": "/v1/operations/op_01JZ7H0A1B2C3D4E5F6G7H8J9K/result",
    "estimated_credits": 0,
    "result_available": false,
    "next_check_at": "2026-06-23T12:00:02+00:00"
  },
  "meta": {
    "request_id": "req_123"
  }
}

The operation id is durable and pollable through Operations. The normal echo response remains synchronous and non-billable.

Billable operation endpoints are different from these foundation endpoints: they need the required token scope and enough credits. Paid use also needs an eligible paid plan, a healthy subscription, and an included operation family; guest and free credentials spend free credits instead (see Free credits and limits). Plan and subscription denials use the billing errors documented in Errors, Rate Limits, and Pagination.