Docs
Sign inStart free

Automation Management

These preview routes keep team-token, scope, and project-access boundaries. Collections use cursors and target failures do not reveal cross-team resources.

POST/v1/operations/estimate

Send operation_key and input. The advisory response includes normalized public input, reserve credits, pricing strategy, separate quota, concurrency, spend, token-budget, and credit decisions, safe cached readiness, effective plan, and estimated_at. Readiness contains the provider-neutral adapter_registered, declared, and effective facts plus explicit safe_checks and omitted_checks; it never exposes an internal adapter name. It creates no operation, hold, pin, callback, provider request, or selected-operation usage. A live start repeats all mutable checks.

Fixed-price operations, scrape/screenshot URL options, conversion artifact_id/file_id metadata, inline translation, inline LLM input, and declared research budgets are supported. Reusable-source translation and an unregistered source mode return HTTP 422 validation_failed. Estimates never open reusable-source bytes, fetch a URL, contact a provider, or resolve callback DNS.

GET/v1/usage

Returns up to 90 days grouped by one of operation_key, family, project, or token. Hourly buckets are limited to 31 days.

GET/v1/credits

Returns spendable balance, a separate free_credits summary, debt, and retained purchased-credit expiry. Free credits are not included in spendable paid balance and are not returned as purchased packages. The response includes free_credit_policy.monthly_refresh: false; free promotional credits are one-off grants and do not refresh monthly.

GET/v1/credits/transactions

Returns customer-safe signed credit activity without ledger internals. An operation ID is included only while the calling key can still read that operation under its current operation scope, project grant, and connected-data authority. Promotional/free-funded operation rows include funding_mode, credit_source, and free_credits_reserved, free_credits_used, or free_credits_released when those values apply.

GET/v1/billing

Returns plan and auto-recharge state.

GET/v1/billing/packages

Lists configured credit packages.

GET/v1/billing/auto-recharge

Returns auto-recharge settings.

PATCH/v1/billing/auto-recharge

Requires billing write scope, idempotency, and an exact management proof.

GET/v1/billing/reconciliation

Returns the latest cached reconciliation report or not_yet_available.

POST/v1/billing/purchases

Creates a pollable pur_... intent after exact human approval. It never accepts payment details. The response is HTTP 202 with Location; pending and pending_reconciliation also include next_check_at and Retry-After. Confirmed fulfillment becomes fulfilled, a known decline becomes failed, and an ambiguous provider outcome becomes pending_reconciliation. Retrying the same idempotency key returns the original purchase and never resends a possibly completed charge. Chab correlates a confirmed subscription charge to its exact purchase before a completion webhook may fulfill the polling resource; concurrent same-package purchases are never paired by creation order.

GET/v1/billing/purchases/{purchase_id}

Returns purchase state. Poll only pending or pending_reconciliation using the returned next_check_at and Retry-After; terminal responses omit the retry header.

GET/v1/projects

Lists projects granted to the current key.

POST/v1/projects

Creates a project when the key has create scope and project mode all.

GET/v1/projects/{project_id}

Returns one currently granted project.

PATCH/v1/projects/{project_id}

Updates a currently granted project.

DELETE/v1/projects/{project_id}

Deletes a project through existing connected-data safeguards.

GET/v1/tokens

Lists redacted token policy and lifecycle metadata.

POST/v1/tokens

Creates a bounded child after management approval; plaintext is returned once. The requested permissions, project access, spending mode, expiry, and IP rules must stay within the calling token's current authority. If the calling token has IP rules, the child request must include ip_rules: allow ranges must stay inside the caller's allow ranges, and deny ranges must preserve the caller's deny ranges. Omitting ip_rules is accepted only when the caller has no IP rules.

GET/v1/tokens/{token_public_id}

Returns safe metadata by the bare UUID public ID.

PATCH/v1/tokens/{token_public_id}

Supply expected_policy_revision plus at least one change. Self-service changes may only narrow current authority, including setting disabled=true; enabling a disabled token or widening another token requires an exact management proof.

POST/v1/tokens/{token_public_id}/revoke

Revokes a token using its expected policy revision.

POST/v1/management-approvals

Creates a five-minute map_... challenge bound to action, target, revision, initiating token, team, and canonical mutation digest.

For a cross-token tokens.revoke challenge, put the policy revision in the top-level expected_policy_revision field and send an empty mutation object:

{
  "action": "tokens.revoke",
  "target_type": "token",
  "target_id": "870b679b-210c-4d33-9d2c-a5b091693f42",
  "expected_policy_revision": 3,
  "mutation": {}
}

The eventual revoke request carries that same revision in its normal request body. The revision is bound separately and is not duplicated inside mutation.

GET/v1/management-approvals/{approval_id}

Poll every two seconds. The first poll after approval returns the proof once. Supply it only through X-Chab-Management-Approval on the bound mutation. The revision is bound separately from the canonical mutation digest, so include the same expected_policy_revision in the eventual token request. Disable automatic retries for the proof-returning GET. If that response is lost, the proof cannot be recovered and a fresh human approval is required. The proof, its initiating token, action, target, revision, and normalized mutation are verified and consumed in the mutation's transaction.

Management approval errors

management_approval_required means the requested token-management mutation needs a completed human approval. billing_action_required is the equivalent state for protected billing mutations. An expired challenge returns management_approval_expired; a proof that is consumed, belongs to another initiating token, or does not exactly match the action, target, revision, and canonical mutation returns management_approval_invalid. Create a new exact approval instead of retrying either terminal proof state.

curl -X POST https://www.chab.ai/v1/operations/estimate
curl https://www.chab.ai/v1/usage
curl https://www.chab.ai/v1/credits
curl https://www.chab.ai/v1/credits/transactions
curl https://www.chab.ai/v1/billing
curl https://www.chab.ai/v1/billing/packages
curl https://www.chab.ai/v1/billing/auto-recharge
curl -X PATCH https://www.chab.ai/v1/billing/auto-recharge
curl https://www.chab.ai/v1/billing/reconciliation
curl -X POST https://www.chab.ai/v1/billing/purchases
curl https://www.chab.ai/v1/billing/purchases/pur_example
curl https://www.chab.ai/v1/projects
curl -X POST https://www.chab.ai/v1/projects
curl https://www.chab.ai/v1/projects/42
curl -X PATCH https://www.chab.ai/v1/projects/42
curl -X DELETE https://www.chab.ai/v1/projects/42
curl https://www.chab.ai/v1/tokens
curl -X POST https://www.chab.ai/v1/tokens
curl https://www.chab.ai/v1/tokens/870b679b-210c-4d33-9d2c-a5b091693f42
curl -X PATCH https://www.chab.ai/v1/tokens/870b679b-210c-4d33-9d2c-a5b091693f42
curl -X POST https://www.chab.ai/v1/tokens/870b679b-210c-4d33-9d2c-a5b091693f42/revoke
curl -X POST https://www.chab.ai/v1/management-approvals
curl https://www.chab.ai/v1/management-approvals/map_example