---
title: "POST /gateways/{gatewayIdentifier}/rules"
method: POST
path: "/gateways/{gatewayIdentifier}/rules"
---

# POST /gateways/{gatewayIdentifier}/rules

`POST /gateways/{gatewayIdentifier}/rules`

Creates a rule for a gateway. Rules define conditions and actions that control how requests are routed and processed through the gateway, including principal-based access control and path-based routing.

## Path parameters

- `gatewayIdentifier` string, required

## Request body

- object
  - `clientToken` string — A unique, case-sensitive identifier to ensure that the API request completes no more than one time. If you don't specify this field, a value is randomly generated for you. If this token matches a previous request, the service ignores the request, but doesn't return an error. For more information, see <a href="https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Run_Instance_Idempotency.html">Ensuring idempotency</a>.
  - `priority` integer, required — The priority of the rule. Rules are evaluated in order of priority, with lower numbers evaluated first. Must be between 1 and 1,000,000.
  - `conditions` Condition[] — The conditions that must be met for the rule to apply. Conditions can match on principals (IAM ARNs) or request paths.
    - `matchPrincipals` object — A condition that matches on the identity of the caller making the request.
      - `anyOf` MatchPrincipalEntry[], required — A list of principal entries. The condition is met if any of the entries match the caller's identity.
        - `iamPrincipal` object — An IAM principal to match against, specified by ARN.
          - `arn` string, required — The Amazon Resource Name (ARN) of the IAM principal. Supports user, role, and assumed-role ARNs. Wildcards can be used with the <code>StringLike</code> operator.
          - `operator` 'StringEquals' | 'StringLike' — The match operator. <code>StringEquals</code> requires an exact match. <code>StringLike</code> supports wildcard patterns using <code>*</code> and <code>?</code>.
    - `matchPaths` object — A condition that matches on the request path.
      - `anyOf` MatchPathPattern[], required — A list of path patterns. The condition is met if the request path matches any of the patterns.
  - `actions` Action[], required — The actions to take when the rule conditions are met. Actions can route to a specific target or apply a configuration bundle override.
    - `configurationBundle` object — An action that applies a configuration bundle override to the request.
      - `staticOverride` object — A static configuration bundle override that applies a single bundle version to all matching requests.
        - `bundleArn` string, required — The Amazon Resource Name (ARN) of the configuration bundle to apply.
        - `bundleVersion` string, required — The version of the configuration bundle to apply.
      - `weightedOverride` object — A weighted configuration bundle override that splits traffic between multiple bundle versions based on configured weights.
        - `trafficSplit` TrafficSplitEntry[], required — The traffic split entries defining how traffic is distributed between configuration bundle versions.
          - `name` string, required — The name of this traffic split variant.
          - `weight` integer, required — The percentage of traffic to route to this variant. Weights across all entries must sum to 100.
          - `configurationBundle` object, required — The configuration bundle reference for this variant.
            - `bundleArn` string, required — The Amazon Resource Name (ARN) of the configuration bundle.
            - `bundleVersion` string, required — The version of the configuration bundle.
          - `description` string — The description of this traffic split variant.
          - `metadata` object — Key-value metadata associated with this traffic split variant.
    - `routeToTarget` object — An action that routes the request to a specific target.
      - `staticRoute` object — A static route that sends all matching requests to a single target.
        - `targetName` string, password, required — The name of the target to route requests to.
      - `weightedRoute` object — A weighted route that splits traffic between multiple targets.
        - `trafficSplit` TargetTrafficSplitEntry[], required — The traffic split entries defining how traffic is distributed between targets.
          - `name` string, required — The name of this traffic split variant.
          - `weight` integer, required — The percentage of traffic to route to this variant.
          - `targetName` string, password, required — The name of the target to route traffic to.
          - `description` string — The description of this traffic split variant.
          - `metadata` object — Key-value metadata associated with this traffic split variant.
  - `description` string — The description of the gateway rule.

## Response `202`

Success

- CreateGatewayRuleResponse
  - `ruleId` string, required — The unique identifier of the gateway rule.
  - `gatewayArn` string, required — The Amazon Resource Name (ARN) of the gateway that the rule belongs to.
  - `priority` integer, required — The priority of the rule. Rules are evaluated in order of priority, with lower numbers evaluated first.
  - `conditions` Condition[] — The conditions that must be met for the rule to apply.
    - `matchPrincipals` object — A condition that matches on the identity of the caller making the request.
      - `anyOf` MatchPrincipalEntry[], required — A list of principal entries. The condition is met if any of the entries match the caller's identity.
        - `iamPrincipal` object — An IAM principal to match against, specified by ARN.
          - `arn` string, required — The Amazon Resource Name (ARN) of the IAM principal. Supports user, role, and assumed-role ARNs. Wildcards can be used with the <code>StringLike</code> operator.
          - `operator` 'StringEquals' | 'StringLike' — The match operator. <code>StringEquals</code> requires an exact match. <code>StringLike</code> supports wildcard patterns using <code>*</code> and <code>?</code>.
    - `matchPaths` object — A condition that matches on the request path.
      - `anyOf` MatchPathPattern[], required — A list of path patterns. The condition is met if the request path matches any of the patterns.
  - `actions` Action[], required — The actions to take when the rule conditions are met.
    - `configurationBundle` object — An action that applies a configuration bundle override to the request.
      - `staticOverride` object — A static configuration bundle override that applies a single bundle version to all matching requests.
        - `bundleArn` string, required — The Amazon Resource Name (ARN) of the configuration bundle to apply.
        - `bundleVersion` string, required — The version of the configuration bundle to apply.
      - `weightedOverride` object — A weighted configuration bundle override that splits traffic between multiple bundle versions based on configured weights.
        - `trafficSplit` TrafficSplitEntry[], required — The traffic split entries defining how traffic is distributed between configuration bundle versions.
          - `name` string, required — The name of this traffic split variant.
          - `weight` integer, required — The percentage of traffic to route to this variant. Weights across all entries must sum to 100.
          - `configurationBundle` object, required — The configuration bundle reference for this variant.
            - `bundleArn` string, required — The Amazon Resource Name (ARN) of the configuration bundle.
            - `bundleVersion` string, required — The version of the configuration bundle.
          - `description` string — The description of this traffic split variant.
          - `metadata` object — Key-value metadata associated with this traffic split variant.
    - `routeToTarget` object — An action that routes the request to a specific target.
      - `staticRoute` object — A static route that sends all matching requests to a single target.
        - `targetName` string, password, required — The name of the target to route requests to.
      - `weightedRoute` object — A weighted route that splits traffic between multiple targets.
        - `trafficSplit` TargetTrafficSplitEntry[], required — The traffic split entries defining how traffic is distributed between targets.
          - `name` string, required — The name of this traffic split variant.
          - `weight` integer, required — The percentage of traffic to route to this variant.
          - `targetName` string, password, required — The name of the target to route traffic to.
          - `description` string — The description of this traffic split variant.
          - `metadata` object — Key-value metadata associated with this traffic split variant.
  - `description` string — The description of the gateway rule.
  - `createdAt` string, date-time, required — The timestamp when the rule was created.
  - `status` 'CREATING' | 'ACTIVE' | 'UPDATING' | 'DELETING', required — The current status of the rule.
  - `system` object — System-managed metadata for rules created by automated processes.
    - `managedBy` string, required — The identifier of the system or process that manages this rule.

## Other responses

- `480` — ServiceQuotaExceededException
- `481` — ConflictException
- `482` — ValidationException
- `483` — AccessDeniedException
- `484` — ResourceNotFoundException
- `485` — ThrottlingException
- `486` — InternalServerException

---

[API](https://skmtc.net/aws/apis/bedrock-agentcore-control.md) · [All operations](https://skmtc.net/aws/apis/bedrock-agentcore-control/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/bedrock-agentcore-control/versions/0ebde766792b/schema)