---
title: "Create or replace an AI Gateway routing policy"
method: POST
path: "/api/v2/policies"
tags: ["AI Gateway"]
---

# Create or replace an AI Gateway routing policy

`POST /api/v2/policies`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/policies`
- 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/policies/post.ts> (a function with typed inputs; its response is checked against the schema)

Create or replace the routing policy document for an inbound pattern. Pass user_id to scope the policy to a user.

## Query parameters

- `user_id` string, uuid

## Request body

- AiGatewayPolicyRequest: Request to create or replace a routing policy document.
  - `data` AiGatewayPolicyRequestData, required: Data used to create or replace a routing policy document.
    - `attributes` AiGatewayPolicyRequestAttributes, required: Attributes used to create or replace a routing policy document.
      - `inbound` string, required: Inbound request pattern.
      - `priority` integer: Routing priority.
      - `tiers` AiGatewayPolicyTierRequest[], required
        - `priority` integer: Routing priority.
        - `targets` AiGatewayPolicyTargetRequest[], 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 retaining a saved target by ID or when its provider is hidden.
          - `provider` string: Provider slug. Omitted for dynamic resolution or when its provider is hidden.
    - `type` 'routing-documents', required: AI Gateway routing policy resource type.

## Response `200`

OK

- AiGatewayPolicyResponse: Response containing one routing policy document.
  - `data` AiGatewayPolicyResource, required: AI Gateway routing policy resource.
    - `attributes` AiGatewayPolicyAttributes, required: Routing policy configuration.
      - `priority` integer, required: Routing priority.
      - `tiers` AiGatewayPolicyTier[], required
        - `targets` AiGatewayPolicyTarget[], required
          - `id` integer, required: 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 retaining a saved target by ID or when its provider is hidden.
          - `priority` integer, required: Routing priority.
          - `provider` string, nullable: Provider slug. Omitted for dynamic resolution or when its provider is hidden.
    - `id` string, required: Resource identifier.
    - `type` 'routing-documents', required: AI Gateway routing policy resource type.

## Other responses

- `400`: Bad Request
- `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)