---
title: "Create a limit policy"
method: POST
path: "/api/limit-policies/"
tags: ["limitPolicies"]
---

# Create a limit policy

`POST /api/limit-policies/`

Create a policy. Returns the full policy, matching the retrieve response. Caps are stored and visible as soon as they are created, but the gateway enforces them only where the limit system is enabled for your environment. Where it is not enabled, a cap records no usage and never blocks.

## Headers

- `Authorization` string, required

## Request body

- LimitPolicyCreateRequest
  - `name` string, required
  - `scope` string — Display category. Not used for matching.
  - `scope_value` string, required — Identity to meter. For composites (`compose` length >= 2), a JSON list of values in `compose` order.
  - `compose` string[]
  - `metric` 'cost' | 'request_count' | 'token_count', required — What the cap counts. `cost` is US dollars, `token_count` is total tokens, `request_count` is calls.
  - `algorithm` 'balance_fixed_window'
  - `period` string, nullable — Named bucket, integer-seconds string, or `null` for cumulative.
  - `anchor` 'calendar' | 'first_event' | 'explicit_ts'
  - `anchor_at` string, date-time, nullable
  - `effective_at` string, date-time, nullable
  - `expires_at` string, date-time, nullable
  - `priority` integer
  - `is_active` boolean
  - `rules` LimitPolicyRule[], required
    - `trigger` object, required — Threshold condition. Common shape: `{"counter": {"operator": "gte", "value": 10000}}`.
    - `severity` 'soft' | 'hard', required — `soft` fires an alert without blocking; `hard` blocks the request with 429.
    - `description` string — Shown in events and alert payloads.
    - `is_active` boolean
    - `notification_method_id` string, nullable — Optional OrganizationNotificationMethod id to ping when this rule trips.

## Response `201`

The created policy.

- LimitPolicy — A stored cap: watch a scope, measure a metric, refill on a cadence, and fire rules at thresholds.
  - `id` string, uuid
  - `name` string — Human label.
  - `scope` string — Display category (e.g. `API Key`, `Model`). Not used for matching.
  - `scope_value` string — Identity to meter. For composites, a JSON list of values in `compose` order.
  - `compose` string[] — Empty for single-dimension policies. Members: `organization_id`, `api_key_id`, `user_id`, `customer_identifier`, `model`, `endpoint`.
  - `metric` 'cost' | 'request_count' | 'token_count' — What the cap counts. `cost` is US dollars, `token_count` is total tokens, `request_count` is calls.
  - `algorithm` 'balance_fixed_window' — `balance_fixed_window` is the shipped algorithm. `token_bucket` is reserved and not yet enforced.
  - `period` string, nullable — Cadence. A named bucket (`minute`, `hour`, `day`, `week`, `month`), a positive integer of seconds as a string, or `null` for a cumulative (lifetime) cap that never resets.
  - `anchor` 'calendar' | 'first_event' | 'explicit_ts' — When a recurring window aligns. `calendar` resets on the boundary (e.g. the 1st of the month).
  - `anchor_at` string, date-time, nullable — Required when `anchor` is not `calendar`.
  - `effective_at` string, date-time, nullable — Active-range start. `null` = live since forever.
  - `expires_at` string, date-time, nullable — Active-range end. `null` = live until deactivated. Must be after `effective_at`.
  - `priority` integer — Higher is checked first.
  - `is_active` boolean
  - `rules` LimitPolicyRule[] — Any number of soft rules and at most one effective hard rule.
    - `trigger` object, required — Threshold condition. Common shape: `{"counter": {"operator": "gte", "value": 10000}}`.
    - `severity` 'soft' | 'hard', required — `soft` fires an alert without blocking; `hard` blocks the request with 429.
    - `description` string — Shown in events and alert payloads.
    - `is_active` boolean
    - `notification_method_id` string, nullable — Optional OrganizationNotificationMethod id to ping when this rule trips.
  - `threshold_value` number, double — First hard-rule threshold; falls back to the largest soft threshold.
  - `meter_definition_id` string — Stable hash of the policy identity. Same identity resolves to the same id across recreations.
  - `current_state` LimitPolicyCurrentState — Live counter for the current window instance.
    - `meter_id` string
    - `interval_start` integer, nullable — Epoch seconds, inclusive.
    - `interval_end` integer, nullable — Epoch seconds, exclusive.
    - `current_value` number, double — Accumulated value in this window.
  - `created_at` string, date-time
  - `updated_at` string, date-time

---

[API](https://skmtc.dev/respan/apis/api-reference.md) · [All operations](https://skmtc.dev/respan/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/respan/api-reference/revisions/764fca4d43e4/schema)