--- title: Replace an AI Gateway routing rule description: Replace a routing rule's tiers. breadcrumbs: Docs > API > Replace an AI Gateway routing rule --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Replace an AI Gateway routing rule ## v2 (latest) {% alert level="warning" %} **Note**: This endpoint is in Preview and is subject to change. If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help.md). {% /alert %} | Datadog site | API endpoint | | ----------------- | ------------------------------------------------------ | | app.datadoghq.com | PUT https://api.datadoghq.com/api/v2/routing-rules | | us3.datadoghq.com | PUT https://api.us3.datadoghq.com/api/v2/routing-rules | | us5.datadoghq.com | PUT https://api.us5.datadoghq.com/api/v2/routing-rules | | app.datadoghq.eu | PUT https://api.datadoghq.eu/api/v2/routing-rules | | ap1.datadoghq.com | PUT https://api.ap1.datadoghq.com/api/v2/routing-rules | | ap2.datadoghq.com | PUT https://api.ap2.datadoghq.com/api/v2/routing-rules | | uk1.datadoghq.com | PUT https://api.uk1.datadoghq.com/api/v2/routing-rules | | app.ddog-gov.com | PUT https://api.ddog-gov.com/api/v2/routing-rules | | us2.ddog-gov.com | PUT https://api.us2.ddog-gov.com/api/v2/routing-rules | ### Overview 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. This endpoint requires the `ai_gateway_config_write` permission. OAuth apps require the `ai_gateway_config_write` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#ai-gateway) to access this endpoint. ### Arguments #### Query Strings | Field | Type | Description | | ----------------- | ------ | -------------------------------------- | | slug [*required*] | string | Organization-unique routing rule slug. | ### Request #### Body Data (required) {% tabs %} {% tab label="Model" %} | Parent field | Field | Type | Description | | ------------ | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | Data used to replace an AI Gateway routing rule. | | data | attributes [*required*] | object | Attributes used to replace an AI Gateway routing rule. | | attributes | tiers [*required*] | [object] | | | tiers | ordering | enum | 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. Allowed enum values: `configured`, `weighted_affinity`. Default: `configured`. | | tiers | targets [*required*] | [object] | | | targets | id | int64 | 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. | | targets | model | string | Model name. Omit when retaining a saved target by ID or selecting a concrete target by model_id. | | targets | model_id | int64 | Opaque model catalog ID for a concrete model target. New selections require provider View; saved selections can be retained without metadata. | | targets | provider | string | Provider slug. weighted_affinity requires an explicit provider and does not allow "*". | | targets | reasoning_level | enum | 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. Allowed enum values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. | | targets | slug | string | Organization-unique routing rule slug. Allowed only in configured tiers. | | targets | type [*required*] | enum | Type of routing target. Allowed enum values: `model`, `routing-rule`. | | targets | weight | int64 | 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. | | data | id [*required*] | string | Resource identifier. | | data | type [*required*] | enum | AI Gateway routing rule resource type. Allowed enum values: `routing-rules`. | {% /tab %} {% tab label="Example" %} ```json { "data": { "attributes": { "tiers": [ { "ordering": "configured", "targets": [ { "id": 901, "model": "gpt-5.2-codex", "model_id": 101, "provider": "prod-us", "reasoning_level": "medium", "slug": "coding-fallback", "type": "model", "weight": 70 } ] } ] }, "id": "coding", "type": "routing-rules" } } ``` {% /tab %} {% /tabs %} ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="Model" %} Response containing one AI Gateway routing rule. | Parent field | Field | Type | Description | | ------------ | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | AI Gateway routing rule resource. | | data | attributes [*required*] | object | Routing rule configuration and metadata. | | attributes | created_at [*required*] | date-time | Time when the resource was created. | | attributes | route_id | int64 | Stable numeric route identifier used by scoped policies. | | attributes | tiers [*required*] | [object] | | | tiers | ordering [*required*] | enum | How a tier orders its targets. Allowed enum values: `configured`, `weighted_affinity`. | | tiers | ordering_issue | enum | 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. Read-only. Allowed enum values: `mixed`, `unknown`. | | tiers | targets [*required*] | [object] | | | targets | id | int64 | 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. | | targets | model | string | Model name or pattern. Omitted when the caller cannot view its provider. | | targets | model_id | int64 | Opaque model catalog ID for a concrete model target. New selections require provider View; saved selections can be retained without metadata. | | targets | provider | string | Provider slug. Omitted for dynamic resolution and when the caller cannot view its provider. | | targets | reasoning_level | enum | 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. Allowed enum values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. | | targets | slug | string | Organization-unique resource slug. | | targets | type [*required*] | enum | Type of routing target. Allowed enum values: `model`, `routing-rule`. | | targets | weight | int64 | Effective relative weight. Returned only for targets in weighted_affinity tiers. | | attributes | updated_at [*required*] | date-time | Time when the resource was last updated. | | data | id [*required*] | string | Resource identifier. | | data | type [*required*] | enum | AI Gateway routing rule resource type. Allowed enum values: `routing-rules`. | {% /tab %} {% tab label="Example" %} ```json { "data": { "attributes": { "created_at": "2026-08-24T12:00:00Z", "route_id": 123, "tiers": [ { "ordering": "configured", "ordering_issue": "mixed", "targets": [ { "id": 901, "model": "gpt-5.2-codex", "model_id": 101, "provider": "prod-us", "reasoning_level": "medium", "slug": "coding-fallback", "type": "model", "weight": 70 } ] } ], "updated_at": "2026-08-24T12:00:00Z" }, "id": "coding", "type": "routing-rules" } } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="400" %} Bad Request {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="404" %} Not Found {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="409" %} Conflict {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="429" %} Too many requests {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% /tabs %} ### Code Example {% tabs %} {% tab label="Curl" %} ```bash # Required query arguments export slug="coding" # Set your Datadog site and credentials export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com # Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" curl -X PUT "https://api.${DD_SITE}/api/v2/routing-rules?slug=${slug}" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \ -d @- << EOF { "data": { "attributes": { "tiers": [ { "ordering": "configured", "targets": [ { "id": 901, "model": "gpt-5.2-codex", "model_id": 101, "provider": "prod-us", "reasoning_level": "medium", "slug": "coding-fallback", "type": "model", "weight": 70 } ] } ] }, "id": "coding", "type": "routing-rules" } } EOF ``` {% /tab %} {% /tabs %}