API ReferenceLimit Policies

Create a limit policy

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.

Authentication

AuthorizationBearer
Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

Request

This endpoint expects an object.
namestringRequired
scope_valuestringRequired

Identity to meter. For composites (compose length >= 2), a JSON list of values in compose order.

metricenumRequiredDefaults to cost

What the cap counts. cost is US dollars, token_count is total tokens, request_count is calls.

ruleslist of objectsRequired
scopestringOptional
Display category. Not used for matching.
composelist of stringsOptional
algorithmenumOptionalDefaults to balance_fixed_window
periodstring or nullOptional

Named bucket, integer-seconds string, or null for cumulative.

anchorenumOptionalDefaults to calendar
anchor_atdatetime or nullOptional
effective_atdatetime or nullOptional
expires_atdatetime or nullOptional
priorityintegerOptionalDefaults to 0
is_activebooleanOptionalDefaults to true

Response

The created policy.
idstringOptionalRead-onlyformat: "uuid"
namestringOptional
Human label.
scopestringOptional

Display category (e.g. API Key, Model). Not used for matching.

scope_valuestringOptional

Identity to meter. For composites, a JSON list of values in compose order.

composelist of stringsOptional

Empty for single-dimension policies. Members: organization_id, api_key_id, user_id, customer_identifier, model, endpoint.

metricenumOptionalDefaults to cost

What the cap counts. cost is US dollars, token_count is total tokens, request_count is calls.

algorithmenumOptionalDefaults to balance_fixed_window

balance_fixed_window is the shipped algorithm. token_bucket is reserved and not yet enforced.

periodstring or nullOptional

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.

anchorenumOptionalDefaults to calendar

When a recurring window aligns. calendar resets on the boundary (e.g. the 1st of the month).

anchor_atdatetime or nullOptional

Required when anchor is not calendar.

effective_atdatetime or nullOptional

Active-range start. null = live since forever.

expires_atdatetime or nullOptional

Active-range end. null = live until deactivated. Must be after effective_at.

priorityintegerOptionalDefaults to 0
Higher is checked first.
is_activebooleanOptionalDefaults to true
ruleslist of objectsOptional
Any number of soft rules and at most one effective hard rule.
threshold_valuedoubleOptionalRead-only

First hard-rule threshold; falls back to the largest soft threshold.

meter_definition_idstringOptionalRead-only
Stable hash of the policy identity. Same identity resolves to the same id across recreations.
current_stateobjectOptional
Live counter for the current window instance.
created_atdatetimeOptionalRead-only
updated_atdatetimeOptionalRead-only