---
title: "Update budgets, subtree caps, thresholds, and categories"
method: PATCH
path: "/wallets/policy"
---

# Update budgets, subtree caps, thresholds, and categories

`PATCH /wallets/policy`

## Request

- Base URL: `https://getsanction.com/api/v1`
- URL: `https://getsanction.com/api/v1/wallets/policy`
- Auth: API key in header `x-mgmt-key`

Partial update of the wallet spend policy. Only fields you send change. Amounts in dollars. Management-plane.

## Request body

- PolicyUpdateRequest: Partial — only the fields you send change. Amounts in dollars.
  - `wallet_id` string, required
  - `daily_token_budget_usd` number
  - `monthly_token_budget_usd` number, nullable
  - `daily_spend_budget_usd` number
  - `monthly_spend_budget_usd` number, nullable: Optional monthly spend cap (dollars). Null disables the monthly limit.
  - `subtree_daily_cap_usd` number, nullable
  - `subtree_daily_token_cap_usd` number, nullable
  - `per_transaction_max_usd` number
  - `auto_approve_under_usd` number
  - `escalate_over_usd` number
  - `allowed_categories` string[]
  - `blocked_categories` string[]
  - `capability_rules` object[]: Ordered capability governance rules (CAP-1): namespaced prefix-glob patterns with block → allow-list → escalate precedence.
    - `pattern` string, required: e.g. skill:install:*, api:github.com/*
    - `effect` 'block' | 'allow' | 'escalate', required
  - `tool_conditions` object[]: Context-conditional tool rules (COND-1): a closed vocabulary, exactly one predicate per rule. The restriction is ACTIVE when the condition holds — outside_hours_utc: [start, end) UTC hours (wrapping midnight allowed), or after_model_calls_today: N persisted model calls by this agent today. Effects are restrictive only; allow-list membership is never conditional.
    - `pattern` string, required: Prefix-glob tool pattern, e.g. deploy.*, *
    - `effect` 'block' | 'escalate', required
    - `when` object, required: Exactly one of:
      - `outside_hours_utc` integer[]
      - `after_model_calls_today` integer
  - `escalation_timeout_mins` integer
  - `escalation_timeout_action` 'deny' | 'approve'

## Response `200`

Updated policy

- PolicyResponse
  - `wallet_id` string
  - `policy` PolicyObject: Wallet spend policy. Amounts in dollars.
    - `daily_token_budget_usd` number
    - `monthly_token_budget_usd` number, nullable: Optional per-seat monthly token cap (dollars). Null = daily budget only.
    - `daily_spend_budget_usd` number
    - `monthly_spend_budget_usd` number, nullable: Optional monthly spend cap (dollars). Null disables the monthly limit.
    - `subtree_daily_cap_usd` number, nullable: Optional tree-wide daily cap for this wallet and all descendants. Null disables subtree cap enforcement.
    - `subtree_daily_token_cap_usd` number, nullable: Optional pooled daily token cap: today's token cost across every seat in this wallet's subtree may not exceed this (gateway enforces pre-call). Null disables.
    - `per_transaction_max_usd` number
    - `auto_approve_under_usd` number: At or under this, auto-approve and never escalate (floor wins over escalation).
    - `escalate_over_usd` number: Over this (and over the auto-approve floor), escalate to a human.
    - `allowed_categories` string[]: Non-empty = allow-list (only these may spend). Empty = allow all.
    - `blocked_categories` string[]
    - `escalation_timeout_mins` integer: 0 = never auto-resolve an escalation.
    - `escalation_timeout_action` 'deny' | 'approve'

## Other responses

- `400`: Invalid policy
- `401`: Missing or invalid management key

---

[API](https://skmtc.dev/getsanction/apis/sanction-agent-governance-api.md) · [All operations](https://skmtc.dev/getsanction/apis/sanction-agent-governance-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getsanction/apis/sanction-agent-governance-api/revisions/c645a9e4b72d?raw)