---
title: "Replace an AI Gateway routing rule"
method: PUT
path: "/api/v2/routing-rules"
tags: ["AI Gateway"]
---

# Replace an AI Gateway routing rule

`PUT /api/v2/routing-rules`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/routing-rules`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `ai_gateway_config_write`
- TypeScript: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/routing-rules/put.ts> (a function with typed inputs; its response is checked against the schema)

Replace a routing rule's tiers. The slug is immutable; data capture is managed independently. This is a full replacement: omitted or null ordering resets the tier to configured, and omitted or null weights in a weighted_affinity tier reset to 1. Omitted or null reasoning_level clears a model destination's reasoning override. Replacing a rule repairs tiers reported with an ordering_issue.

## Query parameters

- `slug` string, required

## Request body

- AiGatewayRoutingRuleReplaceRequest: Request to replace an AI Gateway routing rule.
  - `data` AiGatewayRoutingRuleReplaceData, required: Data used to replace an AI Gateway routing rule.
    - `attributes` AiGatewayRoutingRuleReplaceAttributes, required: Attributes used to replace an AI Gateway routing rule.
      - `tiers` AiGatewayRoutingRuleTierRequest[], required
        - `ordering` 'configured' | 'weighted_affinity', nullable: How a tier orders its targets. Omitted or null defaults to configured, which preserves target order. The weighted_affinity ordering distributes first-choice assignments by relative target weights and accepts only model targets with an explicit provider, without repeated provider and model pairs in the same tier.
        - `targets` AiGatewayRoutingRuleTargetRequest[], required
          - `id` integer: Saved target row ID. On replacement, retain this ID only within its original route and at most once. A stale or foreign ID is rejected.
          - `model` string: Model name. Omit when retaining a saved target by ID or selecting a concrete target by model_id.
          - `model_id` integer: Opaque model catalog ID for a concrete model target. New selections require provider View; saved selections can be retained without metadata.
          - `provider` string: Provider slug. weighted_affinity requires an explicit provider and does not allow "*".
          - `reasoning_level` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable: Optional reasoning effort preference for this model destination. Must be supported by the selected model and provider. For provider "*", every eligible provider must support the level. An explicit value overrides the request's reasoning setting, subject to model-group policy. Omitted or null preserves request and provider behavior; none is an explicit level, not the default. Omitted or null clears an override on full replacement. Routing-rule references cannot set this field; each referenced model destination owns its override. If an override cannot be applied at runtime, the gateway keeps the destination and restores the caller's original reasoning settings, or preserves the provider default when omitted. It rechecks all applicable route and model-group policies against those settings before sending. Model-group max_reasoning_level enforces hard limits; the override is not an additional cap. Normal fallback applies if governance denies the resulting request or the destination cannot otherwise serve it. Metrics and span tags record the override outcome and incompatibility reason. When response headers have not already been committed, `X-Ai-Gateway-Reasoning-Override` reports applied or not_applied for the returned attempt, and `X-Ai-Gateway-Reasoning-Override-Reason` reports the reason when not applied.
          - `slug` string: Organization-unique routing rule slug. Allowed only in configured tiers.
          - `type` 'model' | 'routing-rule', required: Type of routing target.
          - `weight` integer, nullable: Relative weight in a weighted_affinity tier. Omitted or null defaults to 1. Weights need not total 100. Must be omitted or null in configured tiers.
    - `id` string, required: Resource identifier.
    - `type` 'routing-rules', required: AI Gateway routing rule resource type.

## Response `200`

OK

- AiGatewayRoutingRuleResponse: Response containing one AI Gateway routing rule.
  - `data` AiGatewayRoutingRuleResource, required: AI Gateway routing rule resource.
    - `attributes` AiGatewayRoutingRuleAttributes, required: Routing rule configuration and metadata.
      - `created_at` string, date-time, required: Time when the resource was created.
      - `route_id` integer: Stable numeric route identifier used by scoped policies.
      - `tiers` AiGatewayRoutingRuleTier[], required
        - `ordering` 'configured' | 'weighted_affinity', required: How a tier orders its targets.
        - `ordering_issue` 'mixed' | 'unknown': Stored tier ordering is inconsistent. mixed means targets have different supported orderings, and unknown means a target has an unsupported ordering. The tier is reported as configured without weights. Replace the rule to repair it. Omitted for consistent tiers. A forced deletion cannot rewrite a surviving tier with an unknown issue.
        - `targets` AiGatewayRoutingRuleTarget[], required
          - `id` integer: Saved target row ID. On replacement, retain this ID only within its original route and at most once. A stale or foreign ID is rejected.
          - `model` string: Model name or pattern. Omitted when the caller cannot view its provider.
          - `model_id` integer: Opaque model catalog ID for a concrete model target. New selections require provider View; saved selections can be retained without metadata.
          - `provider` string: Provider slug. Omitted for dynamic resolution and when the caller cannot view its provider.
          - `reasoning_level` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable: Optional reasoning effort preference for this model destination. Must be supported by the selected model and provider. For provider "*", every eligible provider must support the level. An explicit value overrides the request's reasoning setting, subject to model-group policy. Omitted or null preserves request and provider behavior; none is an explicit level, not the default. Omitted or null clears an override on full replacement. Routing-rule references cannot set this field; each referenced model destination owns its override. If an override cannot be applied at runtime, the gateway keeps the destination and restores the caller's original reasoning settings, or preserves the provider default when omitted. It rechecks all applicable route and model-group policies against those settings before sending. Model-group max_reasoning_level enforces hard limits; the override is not an additional cap. Normal fallback applies if governance denies the resulting request or the destination cannot otherwise serve it. Metrics and span tags record the override outcome and incompatibility reason. When response headers have not already been committed, `X-Ai-Gateway-Reasoning-Override` reports applied or not_applied for the returned attempt, and `X-Ai-Gateway-Reasoning-Override-Reason` reports the reason when not applied.
          - `slug` string: Organization-unique resource slug.
          - `type` 'model' | 'routing-rule', required: Type of routing target.
          - `weight` integer: Effective relative weight. Returned only for targets in weighted_affinity tiers.
      - `updated_at` string, date-time, required: Time when the resource was last updated.
    - `id` string, required: Resource identifier.
    - `type` 'routing-rules', required: AI Gateway routing rule resource type.

## Other responses

- `400`: Bad Request
- `404`: Not Found
- `409`: Conflict
- `429`: Too many requests

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)