Create Budget

POST /budgets

Create Budget

Create a spending cap. Each target — identified by the scope + scope_ref pair — can hold at most one budget; creating a second one for the same target is rejected with 409. A hard_stop budget makes the gateway reject matching traffic with 429 budget_exceeded once the period's spend reaches limit_cents; without hard_stop the budget only reports the over-limit state. limit_cents: 0 with hard_stop: true blocks all matching traffic immediately, which freezes a target's spend without deleting anything.

Parameters

Request body

Content type: application/json

• scope (string, required): What a budget's spend counts. org caps the whole organization. environment caps one environment. api_key caps one caller API key and provider_key one upstream credential. team is a pool shared by every caller API key bound to the team. member is organization-wide for one member: all caller API keys bound to that member, in any team. team_member gives every member of one team an individual allowance of the same size, counting only their spend through keys bound to both that team and that member.

• scope_ref (string, optional): ID of the target the budget applies to, matching scope. Required for every scope except org, where the caller's own organization is used and this field is ignored.

• display_name (string, required): Human-readable budget name.

• limit_cents (integer, required): Spending limit in USD cents. 0 together with hard_stop: true blocks all matching traffic immediately.

• period (string, required): Calendar window the limit applies to, in UTC: day resets at 00:00, week on Monday 00:00, month on the 1st at 00:00.

• hard_stop (boolean, optional): Reject matching traffic once the limit is reached. Defaults to false: report the over-limit state, keep traffic flowing.

• alert_thresholds (array, optional): Percent-of-limit alert points. Omitted or null means the default ([80]).

Responses

• 201: Created

• budget (object, required): A spending cap on one target. Amounts are integer USD cents.

• budget.id (string, required): Budget ID.

• budget.org_id (string, required): Organization that owns this budget.

• budget.scope (string, required): What a budget's spend counts. org caps the whole organization. environment caps one environment. api_key caps one caller API key and provider_key one upstream credential. team is a pool shared by every caller API key bound to the team. member is organization-wide for one member: all caller API keys bound to that member, in any team. team_member gives every member of one team an individual allowance of the same size, counting only their spend through keys bound to both that team and that member.

• budget.scope_ref (string, required): ID of the target the budget applies to, matching scope: an environment ID, caller API key ID, provider key ID, team ID, or member ID. team_member budgets reference a team ID. For org budgets this holds the organization's internal ID, which differs from the organization identifier used elsewhere in this API. Fixed at creation.

• budget.display_name (string, required): Human-readable budget name.

• budget.limit_cents (integer, required): Spending limit in USD cents.

• budget.period (string, required): Calendar window the limit applies to, in UTC: day resets at 00:00, week on Monday 00:00, month on the 1st at 00:00.

• budget.hard_stop (boolean, required): Whether the gateway rejects matching traffic with 429 budget_exceeded once the period's spend reaches the limit. When false the budget only reports the over-limit state.

• budget.alert_thresholds (array, optional): Percent-of-limit points at which a budget_threshold notification fires once per period, delivered to the organization's enabled notification channels. null means the default ([80]). Values above 100 fire under either enforcement mode and flag overspend: hard_stop rejects new requests once the control plane observes spend at the limit, but it does not cap the cost of requests already admitted, so a hard-stopped budget can settle above 100.

• budget.created_at (string, required): Time when the budget was created.

• budget.updated_at (string, required): Time when the budget was last updated.

• 400: Request body or parameters failed validation.

• error (object, required): Error details.

• error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

• error.message (string, required): Human-readable explanation; safe to surface to operators.

• 401: Missing or invalid bearer. Response fields (application/json): identical to POST /budgets, response 400 above.

• 409: The target already has a budget. Response fields (application/json): identical to POST /budgets, response 400 above.

cURL

curl -X POST '$AISIX_CP/budgets' -H 'Authorization: Bearer $AISIX_TOKEN'