--- title: Create an AI Gateway provider description: Creating a provider requires ai_gateway_config_write. breadcrumbs: Docs > API > Create an AI Gateway provider --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Create an AI Gateway provider ## 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/providers | | us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/providers | | us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/providers | | app.datadoghq.eu | POST https://api.datadoghq.eu/api/v2/providers | | ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/providers | | ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/providers | | uk1.datadoghq.com | POST https://api.uk1.datadoghq.com/api/v2/providers | | app.ddog-gov.com | POST https://api.ddog-gov.com/api/v2/providers | | us2.ddog-gov.com | POST https://api.us2.ddog-gov.com/api/v2/providers | ### Overview Creating a provider requires `ai_gateway_config_write`. No provider View check applies before creation. Create a provider and its initial model catalog. All discovered models are enabled; optional models are added as manually managed entries. The slug is the immutable routing identifier. Provider and initial catalog rows are saved in one transaction. Initial sharing is unavailable: supplying initial_bindings returns 503 with stage initial_permissions and outcome not_saved. A failed database commit can return 503 with stage database_commit and outcome unknown; check the provider list before retrying. Creation without initial_bindings keeps normal unrestricted defaults. 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 provider. | | data | attributes [*required*] | object | Attributes used to create an AI Gateway provider. | | attributes | cost_multiplier | double | Multiplier applied to provider costs. Must be greater than 0 and at most 1000000. Default: `1`. | | attributes | initial_bindings | [object] | Reserved for initial View/Edit permissions. Supplying this attribute, including an empty array or null, returns HTTP 503 before discovery or persistence. Omit it for normal creation. | | initial_bindings | principals [*required*] | [string] | Access principals in type:id form. | | initial_bindings | relation [*required*] | enum | Provider access relation. Editor also grants View. Allowed enum values: `viewer`, `editor`. | | attributes | integration_account_id | string | Provider integration account identifier. | | attributes | integration_config | object | Provider-specific integration configuration. | | integration_config | bedrock_region | string | AWS region used for Bedrock model discovery, routing, and request signing. | | integration_config | foundry_project | string | Azure AI Foundry project name, used to call the project's agents. | | integration_config | foundry_resource_id | string | ARM resource ID of the Azure AI Foundry resource, such as `/subscriptions//resourceGroups//providers/Microsoft.CognitiveServices/accounts/`. Required for `azure_foundry` providers. | | integration_config | location | string | GCP location used for Gemini model discovery and credential resolution. | | integration_config | project_id | string | GCP project ID used for Gemini model discovery and credential resolution. | | integration_config | supported_operations | [string] | Custom provider default for discovered and new manual models. Omit to use Chat Completions. An empty list is invalid. | | attributes | known_provider | enum | Known provider implementation. Allowed enum values: `custom`, `anthropic`, `openai`, `azure_openai`, `bedrock`, `gemini`, `baseten`, `fireworks`, `together`, `typesafe`, `azure_foundry`. | | attributes | models | [object] | Manually managed models to add alongside models discovered from the provider integration. | | models | model_id_canonical [*required*] | string | Provider-independent model identifier. | | models | model_id_wire [*required*] | string | Model identifier sent to the provider. | | models | supported_operations | [string] | Operations supported by the model. | | attributes | name [*required*] | string | Human-readable resource name. | | attributes | slug [*required*] | string | Immutable routing identifier. | | data | type [*required*] | enum | AI Gateway provider resource type. Allowed enum values: `providers`. | {% /tab %} {% tab label="Example" %} ```json { "data": { "attributes": { "cost_multiplier": 1, "initial_bindings": [ { "principals": [ "org:11111111-1111-1111-1111-111111111111" ], "relation": "viewer" } ], "integration_account_id": "account-123", "integration_config": { "bedrock_region": "us-east-1", "foundry_project": "my-project", "foundry_resource_id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/ai/providers/Microsoft.CognitiveServices/accounts/my-foundry", "location": "us-central1", "project_id": "my-gcp-project", "supported_operations": [ "OPENAI_CHAT_COMPLETIONS" ] }, "known_provider": "openai", "models": [ { "model_id_canonical": "gpt-5.2-codex", "model_id_wire": "gpt-5.2-codex-20260801", "supported_operations": [ "OPENAI_CHAT_COMPLETIONS" ] } ], "name": "production-us", "slug": "prod-us" }, "type": "providers" } } ``` {% /tab %} {% /tabs %} ### Response {% tabs %} {% tab label="201" %} Created {% tabs %} {% tab label="Model" %} Response containing one AI Gateway provider. | Parent field | Field | Type | Description | | ------------------ | ----------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | AI Gateway provider resource. | | data | attributes [*required*] | object | AI Gateway provider configuration and metadata. | | attributes | cost_multiplier [*required*] | double | Multiplier applied to provider costs. | | attributes | created_at [*required*] | date-time | Time when the resource was created. | | attributes | integration_account_id [*required*] | string | Provider integration account identifier. | | attributes | integration_config | object | Provider-specific integration configuration. | | integration_config | bedrock_region | string | AWS region used for Bedrock model discovery, routing, and request signing. | | integration_config | foundry_project | string | Azure AI Foundry project name, used to call the project's agents. | | integration_config | foundry_resource_id | string | ARM resource ID of the Azure AI Foundry resource, such as `/subscriptions//resourceGroups//providers/Microsoft.CognitiveServices/accounts/`. Required for `azure_foundry` providers. | | integration_config | location | string | GCP location used for Gemini model discovery and credential resolution. | | integration_config | project_id | string | GCP project ID used for Gemini model discovery and credential resolution. | | integration_config | supported_operations | [string] | Custom provider default for discovered and new manual models. Omit to use Chat Completions. An empty list is invalid. | | attributes | known_provider [*required*] | enum | Known provider implementation. Allowed enum values: `custom`, `anthropic`, `openai`, `azure_openai`, `bedrock`, `gemini`, `baseten`, `fireworks`, `together`, `typesafe`, `azure_foundry`. | | attributes | name [*required*] | string | Human-readable resource name. | | attributes | slug [*required*] | string | Immutable routing identifier. | | attributes | updated_at [*required*] | date-time | Time when the resource was last updated. | | data | id [*required*] | string | Resource identifier. | | data | relationships | object | Provider relationships. | | relationships | models [*required*] | object | Model catalog entries associated with a provider. | | models | data [*required*] | [object] | | | data | id [*required*] | string | Resource identifier. | | data | type [*required*] | enum | Model catalog entry resource type. Allowed enum values: `model-catalog-entries`. | | data | type [*required*] | enum | AI Gateway provider resource type. Allowed enum values: `providers`. | | | included | [object] | Model catalog entries created with the provider. | | included | attributes [*required*] | object | Model catalog entry configuration and metadata. | | attributes | created_at [*required*] | date-time | Time when the resource was created. | | attributes | enabled [*required*] | boolean | Whether the resource is enabled. | | attributes | metadata | object | Optional, typed enrichment for a model catalog entry. Missing properties remain unknown. | | metadata | capabilities [*required*] | object | Model features reported by the enrichment source. Omitted properties are unknown. | | capabilities | attachment | boolean | Whether attachment input is supported. | | capabilities | interleaved_reasoning | boolean | Whether reasoning can be interleaved with tool use. | | capabilities | reasoning | boolean | Whether reasoning is supported. | | capabilities | structured_output | boolean | Whether structured output is supported. | | capabilities | temperature | boolean | Whether temperature can be configured. | | capabilities | tool_call | boolean | Whether tool calls are supported. | | metadata | description | string | Human-readable model description. | | metadata | display_name | string | Human-readable model name. | | metadata | family | string | Model family identifier. | | metadata | kind | enum | Primary model kind. Decision models return a choice or score instead of generated text. Allowed enum values: `language`, `embedding`, `image`, `audio`, `decision`, `reranking`. | | metadata | knowledge_cutoff | string | Knowledge cutoff reported by the source. | | metadata | last_updated | string | Date the source record was last updated. | | metadata | lifecycle | enum | Model lifecycle state. Allowed enum values: `active`, `alpha`, `beta`, `deprecated`. | | metadata | limits [*required*] | object | Token limits reported by the enrichment source. | | limits | context_window_tokens | int64 | Total model context window in tokens. | | limits | max_input_tokens | int64 | Maximum input tokens when reported separately. | | limits | max_output_tokens | int64 | Maximum output tokens. | | metadata | modalities [*required*] | object | Supported model input and output modalities. | | modalities | input | [string] | | | modalities | output | [string] | | | metadata | open_weights | boolean | Whether model weights are openly available. | | metadata | reasoning | object | Supported reasoning controls. Absence means controls are unknown or unavailable. | | reasoning | controls [*required*] | [object] | | | controls | effort_levels | [string] | Supported effort values in provider order for an effort control. | | controls | max_budget_tokens | int64 | Maximum reasoning-token budget. | | controls | min_budget_tokens | int64 | Minimum reasoning-token budget. | | controls | type [*required*] | enum | Reasoning-control mechanism. Allowed enum values: `toggle`, `effort`, `budget_tokens`. | | metadata | reference_pricing | [object] | Provider-specific reference prices from the enrichment source. Omitted for shared canonical-model fallback matches. These do not determine gateway charges. | | reference_pricing | amount [*required*] | string | Exact decimal amount per unit, zero or greater, represented as a string to preserve precision. Supports fixed decimal and exponent notation. | | reference_pricing | component [*required*] | string | Token category priced, such as input, output, cache_read, or cache_write. | | reference_pricing | context_max_tokens | int64 | Largest input length covered by this price. Omitted when there is no upper bound. | | reference_pricing | context_min_tokens [*required*] | int64 | Input length above which this price applies. Zero identifies the base tier. | | reference_pricing | currency [*required*] | string | Currency of the price. The only supported value is USD. | | reference_pricing | mode [*required*] | string | Source mode name. Standard is the base mode; other values, such as fast, are source-defined. | | reference_pricing | service_tier | string | Provider service tier explicitly associated with this mode by the source. Omitted when unknown. | | reference_pricing | unit [*required*] | string | Unit of the quoted amount. The only supported value is million_tokens. | | metadata | release_date | string | Model release date. | | metadata | source [*required*] | object | Provenance for model metadata enrichment. | | source | matched_by [*required*] | enum | Identifier strategy used to match the gateway catalog entry. Date-suffix and shared canonical-model fallback matches produce partial metadata. Allowed enum values: `override`, `wire_id`, `canonical_id`, `wire_id_date_suffix`, `canonical_model`. | | source | model_id [*required*] | string | Model identifier in the metadata source provider catalog. | | source | name [*required*] | string | Metadata source name. | | source | observed_at | date-time | Last successful observation of this valid source record. Retained invalid entries keep their previous timestamp. | | source | provider [*required*] | string | Provider namespace in the metadata source, or canonical for a shared model record. | | source | revision | string | SHA-256 content revision of the source snapshot that supplied this record. | | metadata | status [*required*] | enum | Completeness of the matched source record. Partial also identifies metadata from a base model for a dated snapshot or from a shared canonical-model fallback. Allowed enum values: `available`, `partial`. | | attributes | model_id_canonical [*required*] | string | Provider-independent model identifier. | | attributes | model_id_wire [*required*] | string | Model identifier sent to the provider. | | attributes | provider_id [*required*] | int64 | Provider identifier. | | attributes | source [*required*] | enum | How a model catalog entry is managed. Allowed enum values: `discovered`, `manual`. | | attributes | supported_operations [*required*] | [string] | Operations supported by the model. | | attributes | updated_at [*required*] | date-time | Time when the resource was last updated. | | included | id [*required*] | string | Resource identifier. | | included | type [*required*] | enum | Model catalog entry resource type. Allowed enum values: `model-catalog-entries`. | {% /tab %} {% tab label="Example" %} ```json { "data": { "attributes": { "cost_multiplier": 1, "created_at": "2026-08-24T12:00:00Z", "integration_account_id": "account-123", "integration_config": { "bedrock_region": "us-east-1", "foundry_project": "my-project", "foundry_resource_id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/ai/providers/Microsoft.CognitiveServices/accounts/my-foundry", "location": "us-central1", "project_id": "my-gcp-project", "supported_operations": [ "OPENAI_CHAT_COMPLETIONS" ] }, "known_provider": "openai", "name": "production-us", "slug": "prod-us", "updated_at": "2026-08-24T12:00:00Z" }, "id": "42", "relationships": { "models": { "data": [ { "id": "101", "type": "model-catalog-entries" } ] } }, "type": "providers" }, "included": [ { "attributes": { "created_at": "2026-08-24T12:00:00Z", "enabled": true, "metadata": { "capabilities": { "attachment": false, "interleaved_reasoning": false, "reasoning": false, "structured_output": false, "temperature": false, "tool_call": false }, "description": "string", "display_name": "string", "family": "string", "kind": "string", "knowledge_cutoff": "string", "last_updated": "string", "lifecycle": "string", "limits": { "context_window_tokens": 400000, "max_input_tokens": "integer", "max_output_tokens": 128000 }, "modalities": { "input": [ "text" ], "output": [ "text" ] }, "open_weights": false, "reasoning": { "controls": [ { "effort_levels": [ "high" ], "max_budget_tokens": "integer", "min_budget_tokens": "integer", "type": "effort" } ] }, "reference_pricing": [ { "amount": "2.5", "component": "input", "context_max_tokens": 272000, "context_min_tokens": 0, "currency": "USD", "mode": "standard", "service_tier": "priority", "unit": "million_tokens" } ], "release_date": "string", "source": { "matched_by": "wire_id", "model_id": "gpt-5.2-codex", "name": "models.dev", "observed_at": "2019-09-19T10:00:00.000Z", "provider": "openai", "revision": "string" }, "status": "available" }, "model_id_canonical": "gpt-5.2-codex", "model_id_wire": "gpt-5.2-codex-20260801", "provider_id": 42, "source": "discovered", "supported_operations": [ "OPENAI_CHAT_COMPLETIONS" ], "updated_at": "2026-08-24T12:00:00Z" }, "id": "101", "type": "model-catalog-entries" } ] } ``` {% /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/providers" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \ -d @- << EOF { "data": { "attributes": { "cost_multiplier": 1, "initial_bindings": [ { "principals": [ "org:11111111-1111-1111-1111-111111111111" ], "relation": "viewer" } ], "integration_account_id": "account-123", "integration_config": { "bedrock_region": "us-east-1", "foundry_project": "my-project", "foundry_resource_id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/ai/providers/Microsoft.CognitiveServices/accounts/my-foundry", "location": "us-central1", "project_id": "my-gcp-project", "supported_operations": [ "OPENAI_CHAT_COMPLETIONS" ] }, "known_provider": "openai", "models": [ { "model_id_canonical": "gpt-5.2-codex", "model_id_wire": "gpt-5.2-codex-20260801", "supported_operations": [ "OPENAI_CHAT_COMPLETIONS" ] } ], "name": "production-us", "slug": "prod-us" }, "type": "providers" } } EOF ``` {% /tab %} {% /tabs %}