---
title: "Upsert per-tenant rate-limit overrides (admin only)"
method: PUT
path: "/v1/admin/tenants/{tenant_id}/rate-limits"
---

# Upsert per-tenant rate-limit overrides (admin only)

`PUT /v1/admin/tenants/{tenant_id}/rate-limits`

## Request

- Base URL: `https://api.clichefactory.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.clichefactory.com/v1/admin/tenants/{tenant_id}/rate-limits`
- Auth: none declared

Upsert the override row, then evict the local override-cache entry.

Other replicas on the load balancer pick up the change after their 60 s
cache TTL — see :class:`TenantOverrideCache` for the rationale.

## Path parameters

- `tenant_id` string, required

## Headers

- `X-API-KEY` string, nullable

## Request body

- TenantRateLimitsRequest: Body for ``PUT /v1/admin/tenants/{tenant_id}/rate-limits``. Every numeric field is independently optional: omit a field (or send ``null``) to inherit the default for that knob. Sending all four fields as ``null`` upserts a row with no overrides — equivalent to leaving the row absent and relying on defaults, but keeps the audit columns (``notes`` / ``updated_by`` / ``updated_at``) populated. Server enforces ``> 0`` and the ceilings declared above; values outside that band cause a 400, not a silent clamp, so admins notice a typo instead of getting a quietly wrong limit.
  - `heavy_rate_per_sec` number, nullable
  - `heavy_burst` integer, nullable
  - `general_rate_per_sec` number, nullable
  - `general_burst` integer, nullable
  - `notes` string, nullable
  - `updated_by` string, nullable

## Response `200`

Successful Response

- TenantRateLimitsResponse: Body for ``GET /v1/admin/tenants/{tenant_id}/rate-limits``. Carries: * ``defaults`` — the server-wide :class:`Settings` values, so the admin UI can render placeholders like "Default: 2/s" alongside each input. * ``effective`` — what the limiter would actually use right now (defaults merged with the cached override, per-field). * ``override`` — the raw override row (or ``None`` if no overrides set). * ``ceilings`` — the validation upper bounds so the UI can surface them next to inputs without hard-coding the numbers.
  - `tenant_id` string, required
  - `defaults` object, required
  - `effective` object, required
  - `override` TenantRateLimitsOverride: Raw override row as persisted in ``tenant_rate_overrides``.
    - `tenant_id` string, required
    - `heavy_rate_per_sec` number, nullable
    - `heavy_burst` integer, nullable
    - `general_rate_per_sec` number, nullable
    - `general_burst` integer, nullable
    - `notes` string, nullable
    - `updated_at` string, date-time, nullable
    - `updated_by` string, nullable
  - `ceilings` object, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/clichefactory/apis/aio-server.md) · [All operations](https://skmtc.dev/clichefactory/apis/aio-server/llms.txt) · [OpenAPI document](https://skmtc.dev/clichefactory/apis/aio-server/revisions/9bd59f9bbb31?raw)