---
title: "Set budget alert threshold"
method: PUT
path: "/billing/budget-alert"
tags: ["Billing"]
---

# Set budget alert threshold

`PUT /billing/budget-alert`

## Request

- Base URL: `https://api.mnemom.ai/v1`
- URL: `https://api.mnemom.ai/v1/billing/budget-alert`
- Auth: HTTP bearer

## Request body

- object: Two accepted shapes: (a) LEGACY/ACTIVE — `threshold_cents`: the single scalar low-balance alert, the only shape still honored (fired by the mu-notifications cron); (b) DEPRECATED — `thresholds`: the ordered severity-tiered multi-threshold set, accepted for contract stability but no longer honored (its emitter was retired with the legacy plan model; the response carries `multi_threshold_deprecated: true`). `thresholds` still takes precedence when present; either write resets per-threshold and legacy dedup state.
  - `threshold_cents` integer, nullable
  - `thresholds` object[]: DEPRECATED, DECLARED-BUT-NOT-HONORED (MNE-8422, BG-8). Accepted and persisted for contract stability, but nothing fires these levels anymore — the usage-alerts cron that fired them against PLAN overage cost was retired with the legacy plan model. The response carries `multi_threshold_deprecated: true`. Use the scalar `threshold_cents` low-balance alert instead. Each entry accepts `level` (`warning`|`urgent`|`depleted`, must be unique and rise in severity with value), `value` (non-negative number), an optional `unit` (`cents`, default, or `mu` — 1 µ = 1¢, exact conversion), and an optional `message` (<=500 chars). An empty array clears the configured set.
    - `level` 'warning' | 'urgent' | 'depleted', required
    - `value` number, required
    - `unit` 'cents' | 'mu'
    - `message` string

## Response `200`

Budget alert updated

- object
  - `threshold_cents` integer, nullable: On the multi-threshold write path this mirrors the lowest configured `thresholds[].value_cents` (`null` if the set was cleared); on the legacy write path this echoes the submitted scalar.
  - `thresholds` BudgetAlertThreshold[]: Present on the (deprecated) multi-threshold write path: the normalized, persisted set. DECLARED-BUT-NOT-HONORED (MNE-8422, BG-8) — see `multi_threshold_deprecated`.
    - `level` 'warning' | 'urgent' | 'depleted', required: Severity level. Must rise monotonically with `value_cents` across a configured set.
    - `value_cents` integer, required: Normalized threshold value in integer cents.
    - `message` string: Optional operator-authored message (e.g. an explicit "you are about to lose Mnemom protection features" notice).
  - `multi_threshold_deprecated` boolean: Present and `true` on the multi-threshold write path (MNE-8422, BG-8): the set was accepted and persisted for contract stability but is no longer honored — nothing fires these levels. The scalar `threshold_cents` low-balance alert remains active.
  - `updated` boolean, required

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Forbidden
- `404`: Resource not found
- `429`: Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time.
- `500`: Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error.

---

[API](https://skmtc.dev/mnemom/apis/mnemom-api.md) · [All operations](https://skmtc.dev/mnemom/apis/mnemom-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemom/apis/mnemom-api/revisions/274b7a6ea182?raw)