Skip to main content
These routes cover governance: spend budgets, the audit log, the approval a team lead gives before a risky delegation runs, and a history of approval decisions. For the dashboard side, see Budgets and spend. How budgets behave:
  • A scope is tracked only once it has a budget row. A scope is an agent, a team, a mission (a top-level task and every task delegated under it, keyed by the top-level task’s id) or a tenant. You create rows with POST /api/governance/budgets. Clawboo also creates one when a native agent is created with execConfig.budgetUsd above 0: an agent budget in cap mode.
  • A budget is in warn mode unless you send mode: 'cap'. A warn budget tracks spend and moves to soft_capped from 80% of its limit, but it never pauses anything. Only a cap budget reaches paused at 100% and stops runs.
  • Nothing charges a tenant budget: the route accepts one, but no run records spend against it.
  • Spend is recorded by the server as runs report it, not through these routes. Which runs a hard cap can stop before they spend more depends on the runtime and on how the run started; see Governance.
The audit log is always written. Every route here is on the general rate tier (see rate limits).

Routes

Two separate approval records live here. POST /api/governance/delegation-approval opens a live approval in the tool_call_approvals table and waits for the answer. /api/approvals reads and writes approval_history, a plain log of past allow and deny decisions. The two never write the same table.

GET /api/governance/budgets

Lists every budget, most recently updated first. The route has no filters.
  • Path/query params: none.
  • Request body: none.

Responses

200 OK:
status is active below 80% of the limit and soft_capped from 80%. Only a cap budget becomes paused, at 100%, and stays paused until you resume it or raise its limit. A warn budget stops at soft_capped however far spend goes.

Example


POST /api/governance/budgets

A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example. Creates a budget for a scope, or changes the limit and mode of an existing one. A new budget starts at 0 spent and active. Changing the limit recomputes status from the spend so far, so raising the limit above the current spend un-pauses a cap budget.
  • Path/query params: none.
  • Request body:
Sending mode sets it, on create and on update. Leaving it out keeps an existing budget’s mode, so re-sending a cap budget with only a new limitUsdCents keeps the hard stop. To turn a hard cap into a warning, send mode: 'warn'. A limit of 0 is refused: a budget is a positive limit, and an untracked scope is one with no row. There is no delete route; to stop a cap, change it to warn or raise its limit.

Responses

200 OK: the budget as stored:
400 Bad Request: the body failed validation (an unknown scope, a missing scopeId, a limit that is not a positive integer). details is the zod flatten() output:
Each call writes a budget row to the audit log with the limit and mode before and after, and who asked (see GET /api/governance/audit below).

Example


POST /api/governance/budgets/:scope/:scopeId/resume

A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example. Sets a paused budget back to active. If the spend has already reached the limit, the next recorded cost pauses it again; send graceUsdCents to raise the limit to the current spend plus that amount, so work can continue. A resume with grace keeps the budget’s mode. The response carries willRepause: true when you resume a budget at or over its limit without grace.
  • Path params:
  • Request body (optional):

Responses

200 OK: the resumed budget and the re-pause warning. willRepause is true when spentUsdCents >= limitUsdCents:
400 Bad Request: :scope is not one of the four scopes:
400 Bad Request: the body failed validation (for example a graceUsdCents that is not a positive integer):
404 Not Found: no budget exists for that scope and scopeId:
A resume writes a budget row to the audit log with the budget before and after, and who asked.

Example


GET /api/governance/audit

Reads the append-only audit log, newest first: installs, approvals, tool calls, budget events, cap hits, check results and circuit breaks. There is no write route; the server writes these rows itself. Each row’s summary was scrubbed of secrets when it was written, and is masked again before it is sent. The 80% and 100% budget warnings (eventType: 'budget', summary.reason: 'warn') are written by every run that spends: task-runner runs, OpenClaw Routine fires, team chat (a hand-off, a team turn and its work check’s review), 1:1 chat and the peer exchange. Each is written once, when a charge crosses the line. A task-runner run also writes a budget row when a hard cap stops it (summary.reason is 'auto_pause'), or when its final cost report crossed a cap after the work was done ('cap_reached_at_end'). Team chat, 1:1 chat and the peer exchange write 'auto_pause' on the charge that took a hard cap to 100%. Their rows carry summary.runKind: 'team-chat', 'chat' or 'exchange'. A budget edit writes a budget row too, with summary.reason: 'edit': action ('set_limit' or 'resume'), the scope and scopeId, the spend at the time, the limit, mode and status before (null for a new budget) and after, and who asked: the actor ({ kind: 'person' } for a request that passed the person check, else { kind: 'caller' }), or via: 'agent_create' for a budget set by creating a Clawboo Native agent with one.
  • Query params:
  • Request body: none.

Responses

200 OK: the matching rows (an empty list when nothing matches):

Example


POST /api/governance/delegation-approval

Asks a team lead to approve a risky delegation before it runs. It opens a pending approval in tool_call_approvals (it appears in the approval cards) and holds the request open until the lead answers or the approval expires. The approval’s key is delegate:<kind>, and it is marked neverRemember: every request asks, whatever the lead answered before. The wait is fixed at 5 minutes: the approval expires 5 minutes after it is created, and the request gives up at the same time. CLAWBOO_APPROVAL_TTL_MS (24 hours by default) does not change this wait. It sets how old an abandoned pending approval must be before the hourly cleanup expires it. An expired approval moves no task.
  • Path/query params: none.
  • Request body:

Responses

200 OK: the outcome. Each one writes an approval audit row, except a timeout caused by a server error:
expired means the 5 minutes ran out. timeout means the approval row disappeared, or the server hit an error while waiting: the route never answers 500, it answers timeout. Treat deny, expired and timeout alike: do not run the delegation. An allow_always answer allows this delegation only, exactly like allow_once. The next request opens a new approval. 400 Bad Request: missing leaderAgentId:

Example


GET /api/approvals

Lists stored approval decisions from approval_history, newest first. This is a plain log, separate from the live approvals above.
  • Query params:
  • Request body: none.

Responses

200 OK:
500 Internal Server Error: a database error, with an empty list:

Example


POST /api/approvals

Stores one approval decision in approval_history and returns the stored row.
  • Path/query params: none.
  • Request body:
The row says a person decided, so only a request that passes the person check is stored; any other caller gets 403 { "ok": false, "error": "person_only" } and nothing is written. A resolvedBy key in details is dropped. When the request came through a sign-in proxy whose identity token Clawboo verified, the server writes details.resolvedBy itself, as { id, name, role }.

Responses

200 OK: the stored row (null if the insert returned nothing):
400 Bad Request: one of:
500 Internal Server Error: the insert failed:

Example


Error envelope

The budget, audit and delegation-approval routes answer validation errors as { "error": "<message>" }, adding a zod details object on the budget routes. The budget and audit routes do not catch database errors: one reaches Express’s default handler and comes back as an HTML 500, not JSON. The delegation approval never answers 500; it answers timeout. The /api/approvals routes answer { "ok": false, "error": "<message>" }, and the GET adds records: [] on its 500. The access gate covers every route here, with STUDIO_ACCESS_TOKEN or the per-install token, and the same-origin guard refuses cross-origin browser requests. With the token turned off (STUDIO_ACCESS_TOKEN= set blank), a non-loopback bind stops the server at startup unless CLAWBOO_ALLOW_INSECURE=1 is set. See the REST API overview and Security.
  • Governance: budgets, hard caps, circuit breakers and approvals, and which runs each one covers.
  • Budgets and spend: set a budget in the dashboard, and how spend is counted per runtime.
  • Approvals: where a team lead answers a delegation approval.
  • Verification: what writes verification audit rows.
  • Tools and MCP API: the tool approval queue in the same tool_call_approvals table.
  • Environment variables: CLAWBOO_APPROVAL_TTL_MS and the cleanup interval.
Last modified on November 7, 2026