---
title: "Create or replace a credit budget"
method: PUT
path: "/api/orgs/{orgId}/credit-budgets"
tags: ["credits"]
---

# Create or replace a credit budget

`PUT /api/orgs/{orgId}/credit-budgets`

## Request

- Base URL: `https://api.wizbi.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.wizbi.ai/api/orgs/{orgId}/credit-budgets`
- Auth: none declared

A limit on what the org, a group, a member, a channel or an AI worker (agent) may consume per day or month. `warn` alerts; `cap` runs through the overage (default 20 %), then keeps basic chat alive and blocks heavy work until the period turns; `block` refuses further questions at the limit. Alerts at 70 / 80 / 90 / 100 % by default. The scope id must belong to the organization. Needs the `budgets` component. Audited `credits.budget.put`.

## Path parameters

- `orgId` string, required

## Request body

- CreditBudgetPutBody
  - `budget` CreditBudgetInput, required
    - `budget_id` string: Present = replace this budget of the org; absent = a new one.
    - `scope` 'org' | 'group' | 'person' | 'channel' | 'agent', required
    - `scope_id` string, nullable: group id, member principal id or channel name; omitted/null for `org`. Must belong to the org.
    - `period` 'day' | 'month', required
    - `limit` integer, required
    - `on_exceed` 'warn' | 'cap' | 'block': `warn` alerts only · `cap` runs through the overage, then keeps basic chat alive and blocks heavy work · `block` refuses at the limit.
    - `overage_pct` integer: `cap` only: % past the limit before the hard cap (default 20).
    - `alert_pct` integer[]
    - `enabled` boolean
    - `label` string, nullable

## Response `200`

OK.

- CreditBudgetPutResult
  - `budget` object, required
    - `budget_id` string, required
    - `org_id` string, required
    - `scope` 'org' | 'group' | 'person' | 'channel' | 'agent', required
    - `scope_id` string, nullable, required
    - `period` 'day' | 'month', required
    - `limit` integer, required
    - `on_exceed` 'warn' | 'cap' | 'block'
    - `overage_pct` integer
    - `alert_pct` integer[]
    - `enabled` boolean
    - `label` string, nullable
    - `created_by` string, required
    - `created_at` string, date-time, required
    - `updated_by` string, required
    - `updated_at` string, date-time, required

## Other responses

- `400`: Invalid budget (a scope id that is not a channel name).
- `401`: No resolved context.
- `403`: Not an org admin (`forbidden`), or the component is off (`feature_disabled`).
- `404`: No such budget, group or member in this organization.

---

[API](https://skmtc.dev/wizbi/apis/wizbi-core-api.md) · [All operations](https://skmtc.dev/wizbi/apis/wizbi-core-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wizbi/apis/wizbi-core-api/revisions/5a47416c82ec?raw)