--- title: Create an AI Gateway routing rule description: Create an organization-owned routing rule. breadcrumbs: Docs > API > Create an AI Gateway routing rule --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Create 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 | POST https://api.datadoghq.com/api/v2/routing-rules | | us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/routing-rules | | us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/routing-rules | | app.datadoghq.eu | POST https://api.datadoghq.eu/api/v2/routing-rules | | ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/routing-rules | | ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/routing-rules | | uk1.datadoghq.com | POST https://api.uk1.datadoghq.com/api/v2/routing-rules | | app.ddog-gov.com | POST https://api.ddog-gov.com/api/v2/routing-rules | | us2.ddog-gov.com | POST https://api.us2.ddog-gov.com/api/v2/routing-rules | ### Overview Create an organization-owned routing rule. Data capture overrides are managed independently. Each tier has an ordering, which defaults to configured. A weighted_affinity tier distributes first-choice assignments by relative target weights (1 to 10000, default 1) and accepts only distinct model targets with an explicit provider. Weights need not total 100. Configured tiers must omit weights or set them to null. 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. ### Request #### Body Data (required) {% tabs %} {% tab label="Model" %} | Parent field | Field | Type | Description | | ------------ | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | Data used to create an AI Gateway routing rule. | | data | attributes [*required*] | object | Attributes used to create an AI Gateway routing rule. | | attributes | slug [*required*] | string | Organization-unique resource slug. | | 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 | type [*required*] | enum | AI Gateway routing rule resource type. Allowed enum values: `routing-rules`. | {% /tab %} {% tab label="Example" %} ```json { "data": { "attributes": { "slug": "coding", "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 } ] } ] }, "type": "routing-rules" } } ``` {% /tab %} {% /tabs %} ### Response {% tabs %} {% tab label="201" %} Created {% 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="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 # 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 POST "https://api.${DD_SITE}/api/v2/routing-rules" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \ -d @- << EOF { "data": { "attributes": { "slug": "coding", "tiers": [ { "ordering": "weighted_affinity", "targets": [ { "model": "gpt-5.2-codex", "provider": "prod-us", "type": "model", "weight": 70 }, { "model": "gpt-4o-mini", "provider": "prod-us", "type": "model" } ] } ] }, "type": "routing-rules" } } EOF ``` {% /tab %} {% /tabs %}