Governance API

REST surface for Clawboo’s spend governance: the hard USD budget kill-switch (list / set / resume budgets), the append-only forensic audit log, the delegation-approval handshake, and the persisted approval-decision history. The budget kill-switch and audit are always on; budgets are uncapped by default (a budget row exists only when you create one), so no USD is enforced until you set a cap. These routes live in budgets.ts, governanceAudit.ts, delegationApproval.ts, and approvals.ts. All POST routes read a JSON body parsed by express.json({ limit: '2mb' }).

The atomic spend increment that actually pauses a run happens inside the executor loop (recordSpend under BEGIN IMMEDIATE), not over REST. These routes are the human-facing surface: set a cap, read the ledger, resume a paused scope, and view the audit trail.

Routes

Method	Path	Summary	Stream?
GET	`/api/governance/budgets`	List every budget row	No
POST	`/api/governance/budgets`	Set or raise a budget cap	No
POST	`/api/governance/budgets/:scope/:scopeId/resume`	Resume a paused scope (human override)	No
GET	`/api/governance/audit`	Read the forensic audit log (filterable)	No
POST	`/api/governance/delegation-approval`	Route a delegated child’s risky action to the leader’s approval queue (blocks until resolved)	No
GET	`/api/approvals`	List persisted approval decisions	No
POST	`/api/approvals`	Persist an approval decision	No

Two distinct approval surfaces share this page. POST /api/governance/delegation-approval is the live, blocking handshake over the tool_call_approvals table; it waits for the leader to resolve (or for a TTL to expire). /api/approvals is a separate decision-history log over the approval_history table, a fire-and-forget CRUD of past allow/deny decisions. They do not write the same table.

`GET /api/governance/budgets`

Lists every budget row, newest-updated first. There is no filter on this route; the handler always returns the full list.

Path/query params: none.
Request body: none.

Responses

200 OK: every budget row:

{
  budgets: Array<{
    id: string
    scope: 'agent' | 'mission' | 'team' | 'tenant'
    scopeId: string
    limitUsdCents: number
    spentUsdCents: number // whole-cent display mirror = floor(spentMicroCents / 10000)
    spentMicroCents: number // lossless sub-cent spend accumulator
    status: 'active' | 'soft_capped' | 'paused'
    mode: 'cap' | 'warn'
    tenantId: string | null
    createdAt: number
    updatedAt: number
  }>
}

A cap-mode budget auto-pauses the run at 100% of limitUsdCents (the kill-switch). A warn-mode budget (the default posture) records spend and emits warning events at the 80% / 100% crossings but never reaches paused; its status clamps to soft_capped.

Example

curl http://localhost:18790/api/governance/budgets

`POST /api/governance/budgets`

Sets a budget cap for a scope, or raises an existing cap. A new scope starts at spent 0 / active. Re-setting the limit recomputes status from the existing spend, so raising the cap above the current spend un-pauses the scope (the “raise the cap to resume” path). The body is validated by a zod schema.

Path/query params: none.
Request body:

{
  scope: 'agent' | 'mission' | 'team' | 'tenant'  // required
  scopeId: string                                  // required, min length 1
  limitUsdCents: number                            // required, positive integer (a 0 cap is rejected)
  mode?: 'cap' | 'warn'                             // default 'warn' (track-and-warn)
  tenantId?: string | null
}

A cap of 0 is rejected by the schema (limitUsdCents must be a positive integer). “Uncapped” is the absence of a budget row, not a 0 limit. There is no delete route; to make a scope uncapped again, leave it without a row, or set a large cap and resume it.

Responses

400 Bad Request: the body failed zod validation (wrong scope, missing scopeId, non-positive limitUsdCents, …):

{ "error": "invalid body", "details": {} }

details is the zod flatten() of the validation failure. 200 OK: the upserted budget row:

{
  budget: {
    id: string
    scope: 'agent' | 'mission' | 'team' | 'tenant'
    scopeId: string
    limitUsdCents: number
    spentUsdCents: number
    spentMicroCents: number
    status: 'active' | 'soft_capped' | 'paused'
    mode: 'cap' | 'warn'
    tenantId: string | null
    createdAt: number
    updatedAt: number
  }
}

Example

# A $5.00 hard cap on a team (500 cents, cap-mode auto-pause)
curl -X POST http://localhost:18790/api/governance/budgets \
  -H 'Content-Type: application/json' \
  -d '{"scope":"team","scopeId":"<team-id>","limitUsdCents":500,"mode":"cap"}'

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

Human override: force a paused scope back to active (the kill-switch re-arms on the next crossing). A bare resume of a scope whose spend already meets or exceeds its limit will re-pause on the next cost event; pass graceUsdCents to raise the cap above the current spend so the run can make forward progress. The response surfaces willRepause: true when you resume an at/over-limit scope without grace, so a UI can warn the operator.

Path params:

Param	Type	Notes
`scope`	`'agent' \| 'mission' \| 'team' \| 'tenant'`	Validated; an unknown value returns 400.
`scopeId`	`string`	The scope’s id; matched together with `scope`.

Request body (optional):

{
  graceUsdCents?: number  // positive integer; headroom to grant when still at/over the limit
}

Responses

400 Bad Request: :scope is not one of the four scope names:

{ "error": "invalid scope" }

400 Bad Request: the body failed zod validation (e.g. a non-positive graceUsdCents):

{ "error": "invalid body", "details": {} }

404 Not Found: no budget row exists for that (scope, scopeId):

{ "error": "budget not found" }

200 OK: the resumed budget row plus the re-pause warning flag. willRepause is true when spentUsdCents >= limitUsdCents (you resumed without enough grace and the next cost event re-pauses it):

{
  budget: {
    id: string
    scope: 'agent' | 'mission' | 'team' | 'tenant'
    scopeId: string
    limitUsdCents: number
    spentUsdCents: number
    spentMicroCents: number
    status: 'active' | 'soft_capped' | 'paused'
    mode: 'cap' | 'warn'
    tenantId: string | null
    createdAt: number
    updatedAt: number
  }
  willRepause: boolean
}

Example

# Resume a paused team budget and grant $1.00 (100 cents) of headroom
curl -X POST http://localhost:18790/api/governance/budgets/team/<team-id>/resume \
  -H 'Content-Type: application/json' \
  -d '{"graceUsdCents":100}'

`GET /api/governance/audit`

Reads the append-only forensic audit log: installs, approvals, tool calls, budget events, cap hits, verifications, and circuit breaks, newest first. There is no write endpoint; the audit is written in-process by the subsystems that emit events. Each row’s summary (scrubbed JSON at write time) is masked again at the rendering boundary for credential-shaped keys (defense in depth).

Query params:

Param	Type	Default	Notes
`agentId`	`string`	unset	Filter to one agent.
`eventType`	`'install' \| 'approval' \| 'tool_call' \| 'budget' \| 'cap_hit' \| 'verification' \| 'circuit_break'`	unset	Ignored if not one of these literals.
`since`	`number`	unset	Lower bound on `createdAt` (epoch ms); only used if a finite value `> 0`.
`limit`	`number`	`200`	Clamped to `≤ 1000`; only used if a finite value `> 0`.

Request body: none.

Responses

200 OK: the matching audit rows (always returned, even when empty):

{
  audit: Array<{
    id: string
    eventType:
      'install' | 'approval' | 'tool_call' | 'budget' | 'cap_hit' | 'verification' | 'circuit_break'
    agentId: string | null
    taskId: string | null
    teamId: string | null
    tenantId: string | null
    summary: string // scrubbed + redacted JSON text
    createdAt: number
  }>
}

Example

# The last 50 budget events for one agent
curl "http://localhost:18790/api/governance/audit?agentId=<agent-id>&eventType=budget&limit=50"

`POST /api/governance/delegation-approval`

Plumbs a delegated child’s risky action back to the leader’s approval queue. A prior sticky allow_always for the (leader, scope) pair skips the prompt; otherwise the handler opens a pending row in the tool_call_approvals table (visible in the Approvals UI) and blocks until the leader resolves it or the TTL / poll-deadline expires, so a forgotten approval times out rather than deadlocking. The scope key is delegate:<kind>.

Path/query params: none.
Request body:

{
  leaderAgentId: string       // required
  kind?: string               // delegation kind → scope key 'delegate:<kind>'; default 'code'
  targetAgentName?: string    // the agent the work is delegated to (for the prompt text)
  task?: string               // the delegated task description
  taskId?: string             // the board task this delegation gates (lets the TTL reaper unblock it)
}

Responses

400 Bad Request: missing leaderAgentId:

{ "error": "leaderAgentId required" }

200 OK: a prior sticky allow_always for this leader + scope short-circuits the prompt:

{ "resolution": "allow_always" }

200 OK: no sticky rule, so a pending approval was opened and awaited; the resolution is whatever the leader chose, or a terminal expiry/timeout:

{
  resolution: 'allow_once' | 'allow_always' | 'deny' | 'expired' | 'timeout'
}

expired = the approval’s TTL elapsed before resolution; timeout = the poll-deadline elapsed (or the row vanished). Both are terminal “not approved” outcomes; the caller treats them as a denial.

This route awaits a human decision, so it can hang for the duration of the approval TTL / poll window. The TTL is configurable via CLAWBOO_APPROVAL_TTL_MS; see environment variables. A reaper expires abandoned approvals out-of-band.

Example

curl -X POST http://localhost:18790/api/governance/delegation-approval \
  -H 'Content-Type: application/json' \
  -d '{"leaderAgentId":"<leader-id>","kind":"code","targetAgentName":"Reviewer Boo","task":"run the destructive migration"}'

`GET /api/approvals`

Lists persisted approval decisions from the approval_history table, newest first. This is a decision-history log distinct from the live delegation handshake above. Wrapped in a try/catch; a DB failure returns 500 with an empty records array.

Query params:

Param	Type	Default	Notes
`agentId`	`string`	unset	Filter to one agent; omit for all agents.
`limit`	`number`	`50`	Clamped to the range `[1, 200]`.

Request body: none.

Responses

200 OK: the decision history rows:

{
  ok: true
  records: Array<{
    id: number // autoincrement primary key
    agentId: string
    action: string // 'allow-once' | 'allow-always' | 'deny' (as persisted by POST)
    toolName: string
    details: string | null // JSON text, or null
    createdAt: number
  }>
}

500 Internal Server Error: a DB error; note the empty records:

{ "ok": false, "error": "<message>", "records": [] }

Example

curl "http://localhost:18790/api/approvals?agentId=<agent-id>&limit=50"

`POST /api/approvals`

Persists a single approval decision into the approval_history table and returns the inserted row.

Path/query params: none.
Request body:

{
  agentId: string                                   // required
  action: 'allow-once' | 'allow-always' | 'deny'    // required, validated against this set
  toolName: string                                  // required
  details?: Record<string, unknown> | null          // JSON-stringified before storage
}

Responses

400 Bad Request: the body is missing or not an object:

{ "ok": false, "error": "Invalid JSON body" }

400 Bad Request: a required field (agentId, action, or toolName) is missing/falsy:

{ "ok": false, "error": "agentId, action, and toolName are required" }

400 Bad Request: action is not one of the three allowed values:

{ "ok": false, "error": "Invalid action" }

200 OK: the decision was persisted (record is the inserted row, or null if the insert returned nothing):

{
  ok: true
  record: {
    id: number
    agentId: string
    action: string
    toolName: string
    details: string | null
    createdAt: number
  } | null
}

500 Internal Server Error: an insert failure:

{ "ok": false, "error": "<message>" }

Example

curl -X POST http://localhost:18790/api/approvals \
  -H 'Content-Type: application/json' \
  -d '{"agentId":"<agent-id>","action":"allow-always","toolName":"web_search"}'

Error envelope

The budget, audit, and delegation-approval routes use the standard { error: string } envelope; the budget POST routes also attach a zod details object on validation failures. The /api/approvals routes use a distinct { ok: boolean, error: string } shape; the GET also carries records: [] on its 500, and the POST returns { ok: true, record } / { ok: true, records } on success.

When the server is bound to a loopback interface (the default) there is no auth on /api/*. Binding to a non-loopback interface without STUDIO_ACCESS_TOKEN only logs a warning; setting the token activates the access gate in front of every route here. See security.

Reference

REST API

Packages

Routes

`GET /api/governance/budgets`

Responses

Example

`POST /api/governance/budgets`

Responses

Example

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

Responses

Example

`GET /api/governance/audit`

Responses

Example

`POST /api/governance/delegation-approval`

Responses

Example

`GET /api/approvals`

Responses

Example

`POST /api/approvals`

Responses

Example

Error envelope

See also

​Routes

​GET /api/governance/budgets

​Responses

​Example

​POST /api/governance/budgets

​Responses

​Example

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

​Responses

​Example

​GET /api/governance/audit

​Responses

​Example

​POST /api/governance/delegation-approval

​Responses

​Example

​GET /api/approvals

​Responses

​Example

​POST /api/approvals

​Responses

​Example

​Error envelope

​See also

Routes

`GET /api/governance/budgets`

Responses

Example

`POST /api/governance/budgets`

Responses

Example

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

Responses

Example

`GET /api/governance/audit`

Responses

Example

`POST /api/governance/delegation-approval`

Responses

Example

`GET /api/approvals`

Responses

Example

`POST /api/approvals`

Responses

Example

Error envelope

See also