> ## Documentation Index > Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create an AI Gateway Firewall policy > Create an AI Gateway Firewall policy, a named set of rules that check requests and tool calls. ## OpenAPI ````yaml openapi/ai-gateway.yaml POST /firewall-policies openapi: 3.0.3 info: title: AI Gateway APIs version: 0.1.0 description: | Control-plane HTTP APIs served by the ai-gateway-control service. servers: - url: https://api.ngrok.ai security: - bearerAuth: [] tags: - name: AI Gateway Access Key Configurations description: Manage reusable access key configurations (scope and routing rules). - name: AI Gateway Access Keys description: Manage ngrok-managed access keys associated with AI Gateway endpoints. - name: AI Gateway Configuration description: >- Manage per-account AI Gateway configuration (timeouts, token caps, metadata). - name: AI Gateway API Keys description: Manage customer-facing AI Gateway API Keys. - name: AI Gateway Firewall Policies description: >- Manage Firewall policies, the rules that screen the requests and tool calls an access key's traffic carries. - name: AI Gateway Credits description: >- Purchase AI Gateway credits, via Stripe Checkout or a charge of the saved card, and read purchase/transaction history. - name: AI Gateway Providers description: Manage AI Gateway providers and the models they expose. - name: AI Gateway Custom Providers description: Manage custom AI Gateway providers and the models they expose. - name: AI Gateway Models description: >- Read-only listing of AI Gateway models available to the authenticated account. - name: AI Gateway Provider Keys description: >- Manage the provider keys your account stores for AI Gateway. Access key configurations reference them in routing rule steps. - name: AI Gateway Usage description: >- Read-only AI Gateway usage events and aggregated usage overview for the authenticated account. paths: /firewall-policies: post: tags: - AI Gateway Firewall Policies summary: Create an AI Gateway Firewall policy description: | Create a named set of tool-call screening rules. Attach it to an access key configuration to enforce it on every request the configuration's access keys make. operationId: CreateAIGatewayFirewallPolicy requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AIGatewayFirewallPolicyCreate' responses: '201': description: The created Firewall policy. content: application/json: schema: $ref: '#/components/schemas/AIGatewayFirewallPolicy' default: $ref: '#/components/responses/Error' components: schemas: AIGatewayFirewallPolicyCreate: type: object additionalProperties: false description: A policy needs at least one rule. required: - name - rules properties: name: type: string maxLength: 255 description: User-defined label for this policy. description: type: string maxLength: 255 description: Human-readable description. metadata: type: string maxLength: 4096 description: Arbitrary user-defined metadata. mode: type: string enum: - enforce - audit description: > `enforce` blocks a tool call or request the policy's rules flag. `audit` lets it through and reports the verdict. The mode applies to this policy's rules only: an `audit` policy only reports, even when the account's all-keys policy or a request enforces. Defaults to `enforce`. onError: type: string enum: - block - log description: >- What a tool call or request the decision model could not judge does. Defaults to `block`. environment: type: array maxItems: 32 description: >- Facts about the caller's setup that inform the decision model. They are not rules. items: type: string maxLength: 1000 rules: type: array minItems: 1 maxItems: 48 description: > Every rule of the policy, of every tier, before and after the model. A policy holds up to 48. A key enforces its account's all-keys policy and its configuration's policy together, so it can enforce up to 96, and a request can add up to 48 of its own. items: $ref: '#/components/schemas/AIGatewayFirewallRule' AIGatewayFirewallPolicy: type: object additionalProperties: false required: - id - uri - name - createdAt - updatedAt - createdBy - lastUpdatedBy - accessKeyConfigurationCount - appliesToAllKeys - mode - onError - environment - rules properties: id: type: string description: Unique identifier for this policy. uri: type: string description: URI of this AI Gateway Firewall policy API resource. name: type: string description: User-defined label for this policy. description: type: string description: Human-readable description. metadata: type: string description: Arbitrary user-defined metadata. createdAt: type: string format: date-time description: Timestamp when the policy was created. updatedAt: type: string format: date-time description: Timestamp when the policy was last updated. createdBy: $ref: '#/components/schemas/Ref' lastUpdatedBy: $ref: '#/components/schemas/Ref' accessKeyConfigurationCount: type: integer format: int32 description: >- Number of access key configurations that enforce this policy. 0 when unused. appliesToAllKeys: type: boolean description: >- True when the policy is the account's baseline, set as `firewallPolicyId` on the gateway config. It applies to every key, under each configuration's own policy. mode: type: string enum: - enforce - audit description: > `enforce` blocks a tool call or request the policy's rules flag. `audit` lets it through and reports the verdict. The mode applies to this policy's rules only: an `audit` policy only reports, even when the account's all-keys policy or a request enforces. Defaults to `enforce`. onError: type: string enum: - block - log description: >- What a tool call or request the decision model could not judge does. Defaults to `block`. environment: type: array maxItems: 32 description: >- Facts about the caller's setup that inform the decision model. They are not rules. items: type: string maxLength: 1000 rules: type: array maxItems: 48 description: > Every rule of the policy, of every tier, before and after the model. A policy holds up to 48. A key enforces its account's all-keys policy and its configuration's policy together, so it can enforce up to 96, and a request can add up to 48 of its own. items: $ref: '#/components/schemas/AIGatewayFirewallRule' AIGatewayFirewallRule: type: object additionalProperties: false required: - id - tier properties: id: type: string maxLength: 64 description: >- Rule ID. Lowercase letters, digits, `-`, and `_`. Unique across the policy's rules. name: type: string maxLength: 120 description: Name shown as `[name]` when the rule matches. Defaults to the ID. tier: type: string enum: - hardDeny - softDeny - allow x-enum-varnames: - RuleTierHardDeny - RuleTierSoftDeny - RuleTierAllow description: >- `hardDeny` always blocks a match. `softDeny` blocks a match unless an `allow` rule of the same policy matches the same request or tool call. `allow` never blocks. kind: type: string enum: - regex - decision - tool x-enum-varnames: - RuleKindRegex - RuleKindDecision - RuleKindTool description: >- `regex` matches `pattern`, with no model call. `decision` has the decision model score `instructions`. `tool` matches the names in `tools`, with no model call. Defaults to `decision`. pattern: type: string maxLength: 1000 description: >- RE2 pattern a `regex` rule matches. For a tool call, it matches the call's name and arguments. instructions: type: string maxLength: 8000 description: >- What a `decision` rule matches, in plain language. Required for a `decision` rule. tools: type: array maxItems: 64 description: > Tool names a `tool` rule matches, whole. `*` matches any run of characters, so `mcp__github__*` matches every tool of one MCP server. A `tool` rule reads `tool_calls`, the name of each call the model returns, or `tool_definitions`, the tools a request offers. Required for a `tool` rule. items: type: string maxLength: 128 threshold: type: number format: double minimum: 0 maximum: 1 description: >- Match probability at which a `decision` rule fires. Defaults to 0.6 for a deny rule and 0.7 for an allow rule. targets: type: array description: > What the rule reads, which also sets when it runs. `messages`, `tool_results`, and `tool_definitions` run before the request reaches the model. `tool_calls` runs on each tool call the model returns, and cannot be combined with the others. Defaults to `tool_calls`. items: type: string enum: - messages - tool_results - tool_definitions - tool_calls x-enum-varnames: - RuleTargetMessages - RuleTargetToolResults - RuleTargetToolDefinitions - RuleTargetToolCalls Ref: type: object additionalProperties: false required: - id - uri properties: id: type: string description: Resource identifier. uri: type: string description: URI for locating the resource. Error: type: object additionalProperties: false required: - statusCode - msg - details properties: errorCode: type: string description: Stable ngrok error code when available. statusCode: type: integer format: int32 description: HTTP status code for this error. msg: type: string description: Human-readable error message. details: type: object description: Structured error details. additionalProperties: type: string responses: Error: description: API error response. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.