> ## Documentation Index > Fetch the complete documentation index at: https://docs.barndoor.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a rate-limit policy ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/llm-gateway/admin/rate-limits openapi: 3.1.0 info: title: Barndoor.ai Public API description: Unified public API specification for Barndoor.ai platform version: 2.18.0 servers: - url: https://{host} description: Barndoor public API variables: host: default: platform.barndoor.ai description: >- The host serving your Barndoor deployment. Defaults to production; override it for another environment or a dedicated deployment. security: - ApiKey: [] - OAuth2: - openid - profile - email tags: - name: dlp x-group: Data Control Center - name: identity x-group: Identity - name: llm-gateway x-group: LLM Gateway - name: notification x-group: Notifications - name: policy x-group: Policies - name: registry x-group: MCP Gateway - name: system-management x-group: Log Exports paths: /api/llm-gateway/admin/rate-limits: post: tags: - llm-gateway summary: Create a rate-limit policy operationId: create_rate_limit requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateRateLimitRequest' required: true responses: '200': description: The created record content: application/json: schema: $ref: '#/components/schemas/WithAttribution_RateLimitPolicy' '400': description: Malformed request '401': description: Missing or invalid credentials '403': description: Caller is not permitted to act on this resource in this organization '409': description: Another record in this organization already uses this name or scope components: schemas: CreateRateLimitRequest: type: object required: - name - scope_type properties: change_note: type: - string - 'null' description: |- Optional free-text note explaining why this policy was created (BCP-3998). Surfaced on the row and mirrored into the audit event. member_of_group: type: - string - 'null' description: >- BCP-3814: narrow this policy to the members of one IdP group. Only valid on a broad user-scoped policy (`scope_type = "user"` with neither `scope_id` nor `scope_value`), where the window is already keyed per user — so each member of the group gets their own allowance from this single row. Handler-validated; V67 CHECK is the final safety net. name: type: string requests_per_minute: type: - integer - 'null' format: int32 scope_id: type: - string - 'null' format: uuid scope_type: type: string scope_value: type: - string - 'null' target_mcp_server_id: type: - string - 'null' format: uuid description: >- BCP-4056 Target dimension: when set, the policy only meters requests routed to this MCP server. Replaces the old `mcp_server` scope — that one did work, and moves here for consistency with the other two. target_model_alias: type: - string - 'null' description: |- BCP-4056 Target dimension: matches the user-facing alias from `request.model`. Replaces the old `model` scope, which could never match because `scope_keys()` emits no `(Model, _)` pair. target_provider_id: type: - string - 'null' format: uuid description: >- BCP-4056 Target dimension: when set, the policy only meters traffic routed to this provider. Replaces the old `llm_provider` *scope*, which recorded usage the check path never read. May be combined with `target_upstream_model`; mutually exclusive with `target_model_alias` and `target_mcp_server_id` (handler-validated; V74 CHECKs are the final safety net). target_upstream_model: type: - string - 'null' description: >- BCP-4056 Target dimension refining `target_provider_id`: matches the route's resolved upstream model name. Requires `target_provider_id` — a bare upstream name would string every provider serving that model into one window (handler-enforced). tokens_per_minute: type: - integer - 'null' format: int32 traffic_type: type: string WithAttribution_RateLimitPolicy: allOf: - type: object required: - id - org_id - name - scope_type - traffic_type - enabled properties: enabled: type: boolean id: type: string format: uuid member_of_group: type: - string - 'null' description: >- BCP-3814 membership filter: when set, this policy only applies to requesters whose IdP group membership includes this group name. Only meaningful on a broad user-scoped policy (`scope_type == User` with `scope_id` and `scope_value` both `None`), where the counter key resolves to the requesting user's id — so one policy row gives every *member of the group* their own RPM/TPM allowance, and a user joining the group is limited on their next request with no admin action. DB-enforced by `rate_limit_policies_member_of_group_requires_broad_user` (V66, tightened to exclude `scope_value` by V67). `None` ⇒ org-wide (the pre-BCP-3814 behaviour). Contrast with a `ScopeType::Group` policy, which keys its counter by the group name and so *pools* one limit across all members. name: type: string org_id: type: string format: uuid requests_per_minute: type: - integer - 'null' format: int32 scope_id: type: - string - 'null' format: uuid scope_type: $ref: '#/components/schemas/ScopeType' scope_value: type: - string - 'null' target_mcp_server_id: type: - string - 'null' format: uuid description: >- BCP-4056 Target dimension: when set, the policy only fires on requests routed to this MCP server. The MCP-traffic counterpart of `target_provider_id`, and mutually exclusive with all three LLM target columns (DB-enforced by `rate_limit_policies_mcp_target_exclusive_check`) — no single request carries both an MCP server and an LLM route, so a row naming both could never match. Distinct from a `ScopeType::McpServer` policy, which puts the server on the *identity* axis and so cannot be combined with a user or group. Unlike the other two object-shaped scopes, that one does work — it moves here for consistency and to make "this user's rpm on this server" expressible, not to fix a defect. target_model_alias: type: - string - 'null' description: >- BCP-4056 Target dimension: when set, the policy only fires when the requested model alias (`request.model`) equals this value. Mutually exclusive with the other two LLM `target_*` fields. Together with `target_provider_id`/`target_upstream_model` this replaces `ScopeType::Model`, which could never match anything: `GovernanceIdentity::scope_keys()` deliberately emits no `(Model, _)` pair, so a model-scoped policy rendered as Enabled while enforcing nothing. target_provider_id: type: - string - 'null' format: uuid description: >- BCP-4056 Target dimension: when set, the policy only fires on routes whose provider id equals this value. May be combined with `target_upstream_model` to limit a single model on this provider; mutually exclusive with `target_model_alias` (DB-enforced by `rate_limit_policies_alias_target_exclusive_check`). This replaces `ScopeType::LlmProvider` as the way to express "limit this provider". That scope never worked on the check path — the gateway middleware builds its identity with no `llm_provider_id`, so no `(LlmProvider, _)` scope key exists to match against, while the post-response record path *does* carry one and wrote usage to a counter nothing read. target_upstream_model: type: - string - 'null' description: >- BCP-4056 Target dimension refining `target_provider_id`: when set, the policy only fires on routes whose resolved upstream model name equals this value (string match). Always set alongside a provider (V74 CHECK-enforced) — a bare upstream name would string every provider serving that model into one limit. tokens_per_minute: type: - integer - 'null' format: int32 traffic_type: $ref: '#/components/schemas/TrafficType' - $ref: '#/components/schemas/ChangeAttribution' description: >- An admin-API response for an entity whose core type lives in `ai_governance` and so cannot carry portal-only columns. `TokenBudget` and `RateLimitPolicy` are read by the enforcement path on every request; hanging five display-only fields off them would put portal concerns in the hot path's type and force every governance consumer to carry them. Wrapping instead keeps the enforcement reads (`get_enabled_by_org` and friends) returning the bare governance type, while the admin reads return this. Both halves are `#[serde(flatten)]`, so the wire shape stays the flat object the portal already consumes — same choice `AdminModelPricing` makes. ScopeType: type: string description: |- Scope is the *identity* axis of a budget or rate-limit policy — "who is this policy for?". The *what* (LLM provider, upstream model name, model alias) lives on dedicated `target_*` columns on the row (BCP-2813), not as a scope value. `LlmProvider` and `Model` remain in the enum because `rate_limit_policies` and `model_access_policies` still accept them in their `scope_type` CHECK constraints (V12 / V18 / V22 widenings — a separate scope of work to clean up). For token budgets the CHECK was tightened back to identity-only by `V41__budget_scope_target.sql`, so any `LlmProvider`/`Model` budget row that survived would simply fail to match in `BudgetEnforcer::matched_keys`. enum: - org - team - user - project - api_key - mcp_server - llm_provider - model - agent - role - group TrafficType: type: string enum: - all - llm - mcp ChangeAttribution: type: object description: >- The attribution carried on an admin-configurable row, as returned to the portal. Every field is `Option` and nothing is backfilled: a row that predates V75 has no truthful actor to attribute it to, and inventing one would be worse than rendering a placeholder. Rows pick up attribution on their first write. properties: created_by_email: type: - string - 'null' created_by_name: type: - string - 'null' created_by_user_id: type: - string - 'null' format: uuid last_change_note: type: - string - 'null' description: >- Optional free text explaining *why* the last change was made ("Raised for the Q3 batch job", "Vendor deprecated the old endpoint"). Admin-authored and rendered in the portal, so it is untrusted input: length-capped here, escaped on render. last_modified_at: type: - string - 'null' format: date-time description: >- When the change named by `last_modified_by_*` happened. Its own column rather than the row's `updated_at`, because `updated_at` is bumped by writes nobody is attributed for -- pairing the two would date a named admin's edit to a background job's clock. See the V75 migration for the full reasoning. last_modified_by_email: type: - string - 'null' last_modified_by_name: type: - string - 'null' last_modified_by_user_id: type: - string - 'null' format: uuid securitySchemes: ApiKey: type: http scheme: bearer description: >- A Barndoor API key, sent as `Authorization: Bearer `. Keys are prefixed `bdai_` and are opaque — do not attempt to decode one. Interchangeable with an OAuth 2.0 access token. OAuth2: type: oauth2 x-issuer: https://auth.barndoor.ai/realms/barndoor description: >- An OAuth 2.0 access token from Barndoor's identity provider, sent as `Authorization: Bearer `. Public clients must use PKCE. Interchangeable with an API key. flows: authorizationCode: authorizationUrl: >- https://auth.barndoor.ai/realms/barndoor/protocol/openid-connect/auth tokenUrl: >- https://auth.barndoor.ai/realms/barndoor/protocol/openid-connect/token scopes: openid: Issue an OIDC ID token identifying the caller. profile: Read the caller's basic profile claims. email: Read the caller's email address. offline_access: Issue a refresh token. Optional — no operation requires it. clientCredentials: tokenUrl: >- https://auth.barndoor.ai/realms/barndoor/protocol/openid-connect/token scopes: openid: Issue an OIDC ID token identifying the caller. profile: Read the caller's basic profile claims. email: Read the caller's email address. offline_access: Issue a refresh token. Optional — no operation requires it. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.