--- title: Update an AI Gateway routing rule description: Update a route with ai_gateway_config_write and route View/Edit. breadcrumbs: Docs > API > Update an AI Gateway routing rule --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Update 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 Update a route with `ai_gateway_config_write` and route View/Edit. The slug is immutable; data capture is managed independently. Omitting tiers preserves the entire graph. When tiers are supplied, saved parent-local target IDs retain omitted destination and reasoning, weight, rubric, and default settings. Omitted ordering/classifier settings preserve the saved same-position tier. Explicit null resets nullable settings. New references require View on their resources. A hidden target omitted from tiers must be explicitly listed in removed_target_ids, otherwise the update fails without changes. expected_updated_at rejects stale updates with 409. Sharing-only saves do not replace target rows. Hidden and missing routes return the same 404; visible non-editors receive 403. Inference authorization is unchanged. 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 | Partial route update. Omit tiers to preserve the entire graph, including hidden selections. Saved target IDs retain omitted settings. Replacing tiers must explicitly retain or remove every hidden occurrence. | | attributes | expected_updated_at | date-time | Saved route revision. A mismatched value returns 409 without changes. | | attributes | removed_target_ids | [integer] | Parent-local saved occurrence IDs explicitly removed from the submitted tiers. IDs must be distinct, belong to this route, and not also be retained. | | attributes | tiers | [object] | | | tiers | classifier | object | Decision model and settings for a classified tier. Omission preserves the saved classifier; null clears it. Newly selected models require provider View. | | classifier | confidence_threshold | double | Minimum decision confidence. Omission preserves a saved value; new classifiers and explicit null default to 0.5. | | classifier | context | string | Traffic context for the classifier. Omission preserves saved context. | | classifier | model | string | Decision model on the provider. Omit together with provider to preserve the saved selection. | | classifier | provider | string | Decision-model provider slug. Omit together with model to preserve the saved selection. | | tiers | ordering | enum | How a tier orders its targets. Omission preserves the saved same-position tier on update; null resets to configured. New tiers default to configured. 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. The `classified` ordering is allowed only in the first tier and requires a classifier, destination rubrics, and one default destination. Allowed enum values: `configured`, `weighted_affinity`, `classified`. | | tiers | targets [*required*] | [object] | | | targets | default | boolean | Whether this is the single default classified destination. Omission preserves a saved value; null clears it. | | targets | id | int64 | Saved target row ID. On replacement, retain this ID only within its original route and at most once. A stale, foreign, duplicate, or destination-changing ID is rejected. Hidden route targets can be retained using only this parent-local ID and type. | | 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. On update, omission preserves a saved target override; null explicitly clears it. 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 | rubric | string | Destination rubric in a classified tier. Omission preserves a saved value; null clears it. Must be absent on the default destination. | | targets | slug | string | Organization-unique routing rule slug. New references require route View. Omit to retain a saved target by its parent-local ID. 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. Omission preserves a saved target weight; new targets and explicit null default 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": { "expected_updated_at": "2026-08-24T12:00:00Z", "removed_target_ids": [], "tiers": [ { "classifier": { "confidence_threshold": 0.5, "context": "Requests come from engineers.", "model": "gpt-6-luna", "provider": "openai" }, "ordering": "configured", "targets": [ { "default": false, "id": 901, "model": "gpt-5.2-codex", "model_id": 101, "provider": "prod-us", "reasoning_level": "medium", "rubric": "Short factual questions.", "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 [*required*] | int64 | Stable numeric route identifier used by scoped policies and `ai-gateway-route` restriction policies. | | attributes | tiers [*required*] | [object] | | | tiers | classifier | object | Saved classified-tier settings. Provider and model are empty when the caller cannot view the provider. | | classifier | confidence_threshold [*required*] | double | Minimum decision confidence. | | classifier | context | string | Traffic context for the classifier. | | classifier | model [*required*] | string | Viewable decision model, or an empty string. | | classifier | provider [*required*] | string | Viewable decision-model provider slug, or an empty string. | | tiers | ordering [*required*] | enum | How a tier orders its targets. Allowed enum values: `configured`, `weighted_affinity`, `classified`. | | 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 | default | boolean | Present and true for the default classified destination. | | 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. On update, omission preserves a saved target override; null explicitly clears it. 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 | rubric | string | Destination rubric, present only for non-default targets in classified tiers. | | targets | slug | string | Referenced route slug. Omitted when the caller lacks View; only the parent-local occurrence ID remains. | | 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": [ { "classifier": { "confidence_threshold": 0.5, "context": "Requests come from engineers.", "model": "gpt-6-luna", "provider": "openai" }, "ordering": "configured", "ordering_issue": "mixed", "targets": [ { "default": true, "id": 901, "model": "gpt-5.2-codex", "model_id": 101, "provider": "prod-us", "reasoning_level": "medium", "rubric": "Short factual questions.", "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": { "expected_updated_at": "2026-08-24T12:00:00Z", "removed_target_ids": [ 901 ], "tiers": [ { "classifier": { "confidence_threshold": 0.5, "context": "Requests come from engineers.", "model": "gpt-6-luna", "provider": "openai" }, "ordering": "configured", "targets": [ { "default": false, "id": 901, "model": "gpt-5.2-codex", "model_id": 101, "provider": "prod-us", "reasoning_level": "medium", "rubric": "Short factual questions.", "slug": "coding-fallback", "type": "model", "weight": 70 } ] } ] }, "id": "coding", "type": "routing-rules" } } EOF ``` {% /tab %} {% /tabs %}