limitPolicies

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.

post/api/limit-policies/

Headers

Authorizationstring required

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 body

namestring required

scopestring

Display category. Not used for matching.

scope_valuestring required

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

composestring[]

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'

periodstring nullable

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

anchor'calendar' | 'first_event' | 'explicit_ts'

anchor_atstring date-time nullable

effective_atstring date-time nullable

expires_atstring date-time nullable

priorityinteger

is_activeboolean

Response

The created policy.

idstring uuid

namestring

Human label.

scopestring

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

scope_valuestring

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

composestring[]

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.

periodstring 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_atstring date-time nullable

Required when anchor is not calendar.

effective_atstring date-time nullable

Active-range start. null = live since forever.

expires_atstring date-time nullable

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

priorityinteger

Higher is checked first.

is_activeboolean

threshold_valuenumber double

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

meter_definition_idstring

Stable hash of the policy identity. Same identity resolves to the same id across recreations.

created_atstring date-time

updated_atstring date-time

Changes

No recorded changes to this endpoint across all 1 revision of this API.