Model Provider Service

View as Markdown

A Unity Catalog securable that stores authentication and request configuration for an external model provider, such as OpenAI, Azure OpenAI, or Amazon Bedrock. Model service destinations reference it to send requests to that provider.

A model provider service can be referenced by multiple model services. A model service can route across multiple model provider services for traffic splitting or failover.

Get a model provider serviceGET /api/2.1/unity-catalog/{name=model-provider-services/*}List model provider servicesGET /api/2.1/unity-catalog/model-provider-servicesCreate a model provider servicePOST /api/2.1/unity-catalog/model-provider-servicesUpdate a model provider servicePATCH /api/2.1/unity-catalog/{name=model-provider-services/*}Delete a model provider serviceDELETE /api/2.1/unity-catalog/{name=model-provider-services/*}

ModelProviderService object

A Unity Catalog securable that stores authentication and request configuration for an external model provider, such as OpenAI, Azure OpenAI, or Amazon Bedrock. Model service destinations reference it to send requests to that provider.

A model provider service can be referenced by multiple model services. A model service can route across multiple model provider services for traffic splitting or failover.

namestringImmutable

Resource name of the provider service. Format: model-provider-services/{catalog}.{schema}.{model_provider_service}. Each {...} component is capped at 255 characters individually. Server-derived on Create from parent + model_provider_service_id; required and immutable on Update/Get/Delete.

effective_ownerstringOutput only

Owner of the model provider service.

metastore_idstringOutput only

Metastore hosting the provider service.

create_timestringOutput only

Time the provider service was created.

created_bystringOutput only

Creator identity.

update_timestringOutput only

Time the provider service was last modified.

updated_bystringOutput only

Identity of the last updater.

commentstring

User-provided description.

Constraints: <= 65536 characters

etagstringOutput only

Optimistic concurrency token returned on every read. To make an Update or Delete conditional, pass the last-read value in that request's etag field. In REST responses, this value is a base64 string; URL-encode it when setting the etag query parameter.

configobject

Provider authentication, exposed models, request-forwarding controls, rate limits, and payload logging. Required on Create. On Update, it is required only when config or one of its subpaths appears in update_mask.

Show child attributesHide child attributes

provider_typestringImmutable

External model provider. Required on Create and immutable thereafter. Set the matching provider-specific configuration, such as openai, azure_openai, or amazon_bedrock.

Values:

• EXTERNAL_MODEL_PROVIDER_TYPE_OPENAI
• EXTERNAL_MODEL_PROVIDER_TYPE_AZURE_OPENAI
• EXTERNAL_MODEL_PROVIDER_TYPE_ANTHROPIC
• EXTERNAL_MODEL_PROVIDER_TYPE_AMAZON_BEDROCK
• EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM
• EXTERNAL_MODEL_PROVIDER_TYPE_MICROSOFT_FOUNDRY
• EXTERNAL_MODEL_PROVIDER_TYPE_GEMINI_ENTERPRISE

openaiobject

Show child attributesHide child attributes

directobject

OpenAI configuration with an API key supplied in the request.

Show child attributesHide child attributes

api_keyobject

OpenAI API key. Required when creating the service. Supply the value in api_key.plaintext.

organizationstring

Optional OpenAI organization ID. When set, the platform forwards it as the OpenAI-Organization header.

base_urlstring

Optional custom base URL. Defaults to https://api.openai.com/v1. Use for OpenAI-API-compatible third-party endpoints or in-network proxies.

azure_openaiobject

Show child attributesHide child attributes

directobject

Azure OpenAI endpoint and authentication configuration.

Show child attributesHide child attributes

base_urlstring

Full Azure OpenAI endpoint base URL, e.g. https://myresource.openai.azure.com. Required on Create.

api_keyobject

Azure OpenAI API key. Supply the value in api_key.plaintext. Mutually exclusive with Entra ID and Unity Catalog service credential authentication.

service_credentialobject

Reference to a Unity Catalog service credential authorizing Azure OpenAI requests. On Create, supply service_credential.name in the form credentials/{name}. Required on Create when using service-credential authentication; mutually exclusive with api_key and entra_service_principal. The credential is referenced by name; its value is not carried here. Only supported on Azure-hosted workspaces.

entra_service_principalobject

Entra ID service-principal authentication. Set tenant_id, client_id, and client_secret.plaintext. Mutually exclusive with api_key and service_credential.

anthropicobject

Show child attributesHide child attributes

directobject

Direct authentication with an API key supplied in direct.api_key.plaintext. Required unless relayed is set.

Show child attributesHide child attributes

api_keyobject

Anthropic API key. Required when creating the service. Supply the value in api_key.plaintext.

relayedobject

Relayed authentication. Each inference request supplies the caller's OAuth token, which is forwarded to Anthropic. No Anthropic credential is stored. Mutually exclusive with direct.

amazon_bedrockobject

Show child attributesHide child attributes

directobject

Amazon Bedrock region and authentication configuration.

Show child attributesHide child attributes

regionstring

AWS region where the Bedrock endpoint is hosted (e.g., us-east-1). Required on Create.

service_credentialobject

Reference to a Unity Catalog service credential authorizing Bedrock requests. On Create, supply service_credential.name in the form credentials/{name}. Required on Create when using service-credential authentication; mutually exclusive with aws_access_key. The credential is referenced by name; its value is not carried here. Only supported on AWS-hosted workspaces.

aws_access_keyobject

AWS access-key-pair authentication. Set access_key_id and secret_access_key.plaintext. Mutually exclusive with service_credential.

customobject

Show child attributesHide child attributes

directobject

Endpoint and authentication configuration for the custom provider.

Show child attributesHide child attributes

base_urlstring

Endpoint URL of the OpenAI-compatible service (e.g., https://api.example.com/v1). Required on Create.

api_keyobject

Bearer token forwarded in the Authorization header. Supply the value in api_key.plaintext.

microsoft_foundryobject

Show child attributesHide child attributes

directobject

Microsoft Foundry endpoint and authentication configuration.

Show child attributesHide child attributes

base_urlstring

Microsoft Foundry endpoint URL. Required on Create.

api_keyobject

Microsoft Foundry API key. Supply the value in api_key.plaintext. Mutually exclusive with Entra ID and Unity Catalog service credential authentication.

service_credentialobject

Reference to a Unity Catalog service credential authorizing Microsoft Foundry requests. On Create, supply service_credential.name in the form credentials/{name}. Required on Create when using service-credential authentication; mutually exclusive with api_key and entra_service_principal. The credential is referenced by name; its value is not carried here. Only supported on Azure-hosted workspaces.

entra_service_principalobject

Entra ID service-principal authentication. Set tenant_id, client_id, and client_secret.plaintext. Mutually exclusive with api_key and service_credential.

gemini_enterpriseobject

Show child attributesHide child attributes

directobject

Gemini Enterprise project, region, and authentication configuration.

Show child attributesHide child attributes

api_keyobject

Google Gemini Enterprise API key. Required when creating the service. Supply the value in api_key.plaintext.

project_idstring

GCP project ID hosting the Gemini Enterprise endpoint. Required on Create.

regionstring

GCP region of the Gemini Enterprise endpoint (e.g., us-central1). Required on Create.

allow_all_targetsboolean

When true, accepts any model exposed by the upstream provider; targets is not required and does not restrict routability. When false, only models listed in targets are routable. Defaults to false.

targetsarray of object

Models and provider-native API types exposed by this provider service. Each entry must include at least one native_api_types value. When allow_all_targets is false, at least one entry is required and model service destinations can reference only listed models. When allow_all_targets is true, any upstream model is routable; entries in this list provide API-type metadata without restricting other models.

Show child attributesHide child attributes

modelstring

Provider-side model identifier, such as gpt-5 or claude-opus-4-7. This identifies a model at the upstream provider; it is not a Unity Catalog model resource.

native_api_typesarray of string

Provider-native API types supported by this model, such as openai/v1/chat/completions. At least one value is required. AI Gateway uses these values to translate requests and responses. At most 64 entries of 256 characters each are allowed.

forward_headersboolean

Whether to forward incoming HTTP headers to the upstream provider. Defaults to false and is configured for the entire provider service, not per request. Upstream authentication is configured separately in the provider-specific configuration.

forward_query_parametersboolean

Whether to forward incoming query parameters to the upstream provider. Defaults to false and is configured for the entire provider service, not per request.

forward_unmanaged_pathsboolean

Whether to proxy paths that AI Gateway does not recognize as configured provider-native API types. Defaults to false. When true, these paths are forwarded unchanged to the upstream provider. When false, only recognized API paths are served. Enabling this broadens the upstream API surface exposed through the provider service.

rate_limitsarray of object

Rate limits for requests sent directly to this provider service. Requests routed through a model service use that model service's rate limits instead.

Show child attributesHide child attributes

keystring

Scope of the rate limit. Depending on this value, the limit applies to a principal, the service as a whole, or each user by default.

Values:

• RATE_LIMIT_KEY_USER
• RATE_LIMIT_KEY_USER_GROUP
• RATE_LIMIT_KEY_SERVICE_PRINCIPAL
• RATE_LIMIT_KEY_SERVICE
• RATE_LIMIT_KEY_USER_DEFAULT

renewal_periodstring

Renewal period.

Values:

• RATE_LIMIT_RENEWAL_PERIOD_MINUTE
• RATE_LIMIT_RENEWAL_PERIOD_HOUR

principalstring

Principal this limit applies to: user email, group name, or service principal application ID. Required when key applies to a user, group, or service principal; otherwise it must be unset.

requestsint64

Maximum requests allowed in one renewal period. Leave unset for no request limit. Set to 0 to deny all requests.

tokensint64

Maximum tokens allowed in one renewal period. Leave unset for no token limit. Set to 0 to deny all requests.

inference_tableobject

Payload logging configuration for requests sent directly to this provider service. Requests routed through a model service are captured by that model service's inference table instead.

Show child attributesHide child attributes

parentstring

Parent Unity Catalog schema where the inference table is created, in the form schemas/{catalog}.{schema}. Required when configuring an inference table. After the inference table is created, this field cannot be changed.

table_name_prefixstring

Prefix used to form the inference table's registered name. AI Gateway appends _payload; for example, table_name_prefix = "orders" creates orders_payload. If unset, the prefix defaults to the service name. Read table from the response for the resulting resource name. After the inference table is created, this field cannot be changed.

tablestringOutput only

Resolved UC table for payload logs. Format: tables/{catalog}.{schema}.{table}.

is_deletedbooleanOutput only

Whether the referenced inference table has been deleted. The configuration remains visible so you can identify the broken dependency. Payload logging cannot continue until the table is restored or the configuration is updated.

View as Markdown

The ModelProviderService object

{
  "name": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "create_time": "string",
  "created_by": "string",
  "update_time": "string",
  "updated_by": "string",
  "comment": "string",
  "etag": "string",
  "config": {
    "provider_type": "string",
    "openai": {},
    "azure_openai": {},
    "anthropic": {},
    "amazon_bedrock": {},
    "custom": {},
    "microsoft_foundry": {},
    "gemini_enterprise": {},
    "allow_all_targets": true,
    "targets": [
      {}
    ],
    "forward_headers": true,
    "forward_query_parameters": true,
    "forward_unmanaged_paths": true,
    "rate_limits": [
      {}
    ],
    "inference_table": {}
  }
}

Get a model provider service GA

GET /api/2.1/unity-catalog/{name=model-provider-services/*}

Returns the model provider service identified by its resource name.

You must be the owner of the model provider service or have EXECUTE, READ_METADATA, or MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

API scopes: unity-catalog

Parameters

namestringRequiredpath

Resource name of the model provider service. Format: model-provider-services/{catalog}.{schema}.{model_provider_service}. Each {...} component is capped at 255 characters individually.

Response

Returns the ModelProviderService object.

View as Markdown

Response

{
  "name": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "create_time": "string",
  "created_by": "string",
  "update_time": "string",
  "updated_by": "string",
  "comment": "string",
  "etag": "string",
  "config": {
    "provider_type": "string",
    "openai": {},
    "azure_openai": {},
    "anthropic": {},
    "amazon_bedrock": {},
    "custom": {},
    "microsoft_foundry": {},
    "gemini_enterprise": {},
    "allow_all_targets": true,
    "targets": [
      {}
    ],
    "forward_headers": true,
    "forward_query_parameters": true,
    "forward_unmanaged_paths": true,
    "rate_limits": [
      {}
    ],
    "inference_table": {}
  }
}

List model provider services GA

GET /api/2.1/unity-catalog/model-provider-services

Lists the model provider services in a Unity Catalog schema. Provide parent as schemas/{catalog}.{schema}. Results are paginated; pass the returned next_page_token to fetch subsequent pages.

Requires USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema. Only model provider services the caller can access (as owner or through EXECUTE, READ_METADATA, or MANAGE) are returned.

API scopes: unity-catalog

Parameters

parentstringquery

Parent schema to list within, in the form schemas/{catalog}.{schema}. Required. Each {...} component is capped at 255 characters individually.

page_sizeint32query

Maximum number of provider services to return. Defaults to 100 when unset or 0; the maximum is 100. Use page_token to retrieve additional pages.

Constraints: <= 100

page_tokenstringquery

Opaque pagination token from the previous response.

viewstringquery

Fields to return for each service. FULL includes resolved service-credential and inference-table details and rate-limit principal names. BASIC omits those details and principal names from rate limits. Defaults to BASIC when unset.

Values:

• VIEW_UNSPECIFIED
• FULL
• BASIC

Response

Returns a list of ModelProviderService objects.

View as Markdown

Response

{
  "model_provider_services": [
    {
      "name": "string",
      "effective_owner": "string",
      "metastore_id": "string",
      "create_time": "string",
      "created_by": "string",
      "update_time": "string",
      "updated_by": "string",
      "comment": "string",
      "etag": "string",
      "config": {}
    }
  ],
  "next_page_token": "string"
}

Create a model provider service GA

POST /api/2.1/unity-catalog/model-provider-services

Creates a model provider service in a Unity Catalog schema. A model provider service stores authentication and request configuration for an external model provider, such as OpenAI, Azure OpenAI, or Amazon Bedrock. Model services reference it to invoke the provider. Specify its name in model_provider_service_id.

You must be the owner of the parent schema or have the CREATE_SERVICE and USE_SCHEMA privileges on the parent schema and USE_CATALOG on the parent catalog. Inline credentials additionally require CREATE_CONNECTION on the parent schema. When using a Unity Catalog service credential, you must have ACCESS on that credential.

API scopes: unity-catalog

Parameters

parentstringRequiredquery

Name of the parent schema. Format: schemas/{catalog}.{schema}. Each {...} component is capped at 255 characters individually.

model_provider_service_idstringRequiredquery

Name for the model provider service, e.g. "openai_prod".

Request body

The model provider service to create. Do not set name; the server derives it from parent and model_provider_service_id.

namestringImmutable

Resource name of the provider service. Format: model-provider-services/{catalog}.{schema}.{model_provider_service}. Each {...} component is capped at 255 characters individually. Server-derived on Create from parent + model_provider_service_id; required and immutable on Update/Get/Delete.

commentstring

User-provided description.

Constraints: <= 65536 characters

configobject

Provider authentication, exposed models, request-forwarding controls, rate limits, and payload logging. Required on Create. On Update, it is required only when config or one of its subpaths appears in update_mask.

Show child attributesHide child attributes

provider_typestringImmutable

External model provider. Required on Create and immutable thereafter. Set the matching provider-specific configuration, such as openai, azure_openai, or amazon_bedrock.

Values:

• EXTERNAL_MODEL_PROVIDER_TYPE_OPENAI
• EXTERNAL_MODEL_PROVIDER_TYPE_AZURE_OPENAI
• EXTERNAL_MODEL_PROVIDER_TYPE_ANTHROPIC
• EXTERNAL_MODEL_PROVIDER_TYPE_AMAZON_BEDROCK
• EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM
• EXTERNAL_MODEL_PROVIDER_TYPE_MICROSOFT_FOUNDRY
• EXTERNAL_MODEL_PROVIDER_TYPE_GEMINI_ENTERPRISE

openaiobject

Show child attributesHide child attributes

directobject

OpenAI configuration with an API key supplied in the request.

Show child attributesHide child attributes

api_keyobject

OpenAI API key. Required when creating the service. Supply the value in api_key.plaintext.

organizationstring

Optional OpenAI organization ID. When set, the platform forwards it as the OpenAI-Organization header.

base_urlstring

Optional custom base URL. Defaults to https://api.openai.com/v1. Use for OpenAI-API-compatible third-party endpoints or in-network proxies.

azure_openaiobject

Show child attributesHide child attributes

directobject

Azure OpenAI endpoint and authentication configuration.

Show child attributesHide child attributes

base_urlstring

Full Azure OpenAI endpoint base URL, e.g. https://myresource.openai.azure.com. Required on Create.

api_keyobject

Azure OpenAI API key. Supply the value in api_key.plaintext. Mutually exclusive with Entra ID and Unity Catalog service credential authentication.

service_credentialobject

Reference to a Unity Catalog service credential authorizing Azure OpenAI requests. On Create, supply service_credential.name in the form credentials/{name}. Required on Create when using service-credential authentication; mutually exclusive with api_key and entra_service_principal. The credential is referenced by name; its value is not carried here. Only supported on Azure-hosted workspaces.

entra_service_principalobject

Entra ID service-principal authentication. Set tenant_id, client_id, and client_secret.plaintext. Mutually exclusive with api_key and service_credential.

anthropicobject

Show child attributesHide child attributes

directobject

Direct authentication with an API key supplied in direct.api_key.plaintext. Required unless relayed is set.

Show child attributesHide child attributes

api_keyobject

Anthropic API key. Required when creating the service. Supply the value in api_key.plaintext.

relayedobject

Relayed authentication. Each inference request supplies the caller's OAuth token, which is forwarded to Anthropic. No Anthropic credential is stored. Mutually exclusive with direct.

amazon_bedrockobject

Show child attributesHide child attributes

directobject

Amazon Bedrock region and authentication configuration.

Show child attributesHide child attributes

regionstring

AWS region where the Bedrock endpoint is hosted (e.g., us-east-1). Required on Create.

service_credentialobject

Reference to a Unity Catalog service credential authorizing Bedrock requests. On Create, supply service_credential.name in the form credentials/{name}. Required on Create when using service-credential authentication; mutually exclusive with aws_access_key. The credential is referenced by name; its value is not carried here. Only supported on AWS-hosted workspaces.

aws_access_keyobject

AWS access-key-pair authentication. Set access_key_id and secret_access_key.plaintext. Mutually exclusive with service_credential.

customobject

Show child attributesHide child attributes

directobject

Endpoint and authentication configuration for the custom provider.

Show child attributesHide child attributes

base_urlstring

Endpoint URL of the OpenAI-compatible service (e.g., https://api.example.com/v1). Required on Create.

api_keyobject

Bearer token forwarded in the Authorization header. Supply the value in api_key.plaintext.

microsoft_foundryobject

Show child attributesHide child attributes

directobject

Microsoft Foundry endpoint and authentication configuration.

Show child attributesHide child attributes

base_urlstring

Microsoft Foundry endpoint URL. Required on Create.

api_keyobject

Microsoft Foundry API key. Supply the value in api_key.plaintext. Mutually exclusive with Entra ID and Unity Catalog service credential authentication.

service_credentialobject

Reference to a Unity Catalog service credential authorizing Microsoft Foundry requests. On Create, supply service_credential.name in the form credentials/{name}. Required on Create when using service-credential authentication; mutually exclusive with api_key and entra_service_principal. The credential is referenced by name; its value is not carried here. Only supported on Azure-hosted workspaces.

entra_service_principalobject

Entra ID service-principal authentication. Set tenant_id, client_id, and client_secret.plaintext. Mutually exclusive with api_key and service_credential.

gemini_enterpriseobject

Show child attributesHide child attributes

directobject

Gemini Enterprise project, region, and authentication configuration.

Show child attributesHide child attributes

api_keyobject

Google Gemini Enterprise API key. Required when creating the service. Supply the value in api_key.plaintext.

project_idstring

GCP project ID hosting the Gemini Enterprise endpoint. Required on Create.

regionstring

GCP region of the Gemini Enterprise endpoint (e.g., us-central1). Required on Create.

allow_all_targetsboolean

When true, accepts any model exposed by the upstream provider; targets is not required and does not restrict routability. When false, only models listed in targets are routable. Defaults to false.

targetsarray of object

Models and provider-native API types exposed by this provider service. Each entry must include at least one native_api_types value. When allow_all_targets is false, at least one entry is required and model service destinations can reference only listed models. When allow_all_targets is true, any upstream model is routable; entries in this list provide API-type metadata without restricting other models.

Show child attributesHide child attributes

modelstringRequired

Provider-side model identifier, such as gpt-5 or claude-opus-4-7. This identifies a model at the upstream provider; it is not a Unity Catalog model resource.

native_api_typesarray of string

Provider-native API types supported by this model, such as openai/v1/chat/completions. At least one value is required. AI Gateway uses these values to translate requests and responses. At most 64 entries of 256 characters each are allowed.

forward_headersboolean

Whether to forward incoming HTTP headers to the upstream provider. Defaults to false and is configured for the entire provider service, not per request. Upstream authentication is configured separately in the provider-specific configuration.

forward_query_parametersboolean

Whether to forward incoming query parameters to the upstream provider. Defaults to false and is configured for the entire provider service, not per request.

forward_unmanaged_pathsboolean

Whether to proxy paths that AI Gateway does not recognize as configured provider-native API types. Defaults to false. When true, these paths are forwarded unchanged to the upstream provider. When false, only recognized API paths are served. Enabling this broadens the upstream API surface exposed through the provider service.

rate_limitsarray of object

Rate limits for requests sent directly to this provider service. Requests routed through a model service use that model service's rate limits instead.

Show child attributesHide child attributes

keystringRequired

Scope of the rate limit. Depending on this value, the limit applies to a principal, the service as a whole, or each user by default.

Values:

• RATE_LIMIT_KEY_USER
• RATE_LIMIT_KEY_USER_GROUP
• RATE_LIMIT_KEY_SERVICE_PRINCIPAL
• RATE_LIMIT_KEY_SERVICE
• RATE_LIMIT_KEY_USER_DEFAULT

renewal_periodstringRequired

Renewal period.

Values:

• RATE_LIMIT_RENEWAL_PERIOD_MINUTE
• RATE_LIMIT_RENEWAL_PERIOD_HOUR

principalstring

Principal this limit applies to: user email, group name, or service principal application ID. Required when key applies to a user, group, or service principal; otherwise it must be unset.

requestsint64

Maximum requests allowed in one renewal period. Leave unset for no request limit. Set to 0 to deny all requests.

tokensint64

Maximum tokens allowed in one renewal period. Leave unset for no token limit. Set to 0 to deny all requests.

inference_tableobject

Payload logging configuration for requests sent directly to this provider service. Requests routed through a model service are captured by that model service's inference table instead.

Show child attributesHide child attributes

parentstringRequired

Parent Unity Catalog schema where the inference table is created, in the form schemas/{catalog}.{schema}. Required when configuring an inference table. After the inference table is created, this field cannot be changed.

table_name_prefixstring

Prefix used to form the inference table's registered name. AI Gateway appends _payload; for example, table_name_prefix = "orders" creates orders_payload. If unset, the prefix defaults to the service name. Read table from the response for the resulting resource name. After the inference table is created, this field cannot be changed.

Response

Returns the ModelProviderService object.

View as Markdown

Request

{
  "name": "string",
  "comment": "string",
  "config": {
    "provider_type": "string",
    "openai": {},
    "azure_openai": {},
    "anthropic": {},
    "amazon_bedrock": {},
    "custom": {},
    "microsoft_foundry": {},
    "gemini_enterprise": {},
    "allow_all_targets": true,
    "targets": [
      {}
    ],
    "forward_headers": true,
    "forward_query_parameters": true,
    "forward_unmanaged_paths": true,
    "rate_limits": [
      {}
    ],
    "inference_table": {}
  }
}

Response

{
  "name": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "create_time": "string",
  "created_by": "string",
  "update_time": "string",
  "updated_by": "string",
  "comment": "string",
  "etag": "string",
  "config": {
    "provider_type": "string",
    "openai": {},
    "azure_openai": {},
    "anthropic": {},
    "amazon_bedrock": {},
    "custom": {},
    "microsoft_foundry": {},
    "gemini_enterprise": {},
    "allow_all_targets": true,
    "targets": [
      {}
    ],
    "forward_headers": true,
    "forward_query_parameters": true,
    "forward_unmanaged_paths": true,
    "rate_limits": [
      {}
    ],
    "inference_table": {}
  }
}

Update a model provider service GA

PATCH /api/2.1/unity-catalog/{name=model-provider-services/*}

Updates a model provider service. Only the fields named in update_mask are changed; the resource name and provider type are immutable. Optionally supply an etag to make the update conditional on the model provider service not having changed since it was read.

You must be the owner of the model provider service or have MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

Updating config.provider cannot change the provider type or switch between Unity Catalog service-credential authentication and inline authentication.

API scopes: unity-catalog

Parameters

namestringRequiredImmutablepath

Resource name of the provider service. Format: model-provider-services/{catalog}.{schema}.{model_provider_service}. Each {...} component is capped at 255 characters individually. Server-derived on Create from parent + model_provider_service_id; required and immutable on Update/Get/Delete.

update_maskstringRequiredquery

Fields to update. Use config to replace the entire configuration. The replacement must include every required field; any optional field you omit is cleared. To preserve sibling fields, use one or more granular paths: comment; config.provider to replace the active provider-specific value (for example, config.openai; the mask path remains config.provider); config.allow_all_targets, config.targets, config.forward_headers, config.forward_query_parameters, config.forward_unmanaged_paths, config.rate_limits, or config.inference_table. The provider type is immutable, and wildcard paths such as * are not supported.

etagstringquery

Optimistic concurrency token from the most recent read. When set, the update succeeds only if the resource has not changed. Leave unset for an unconditional update. For REST requests, URL-encode the base64 string returned by the API when setting the etag query parameter.

Request body

The model provider service with the updated field values. name identifies the resource (model-provider-services/{catalog}.{schema}.{model_provider_service}); only fields listed in update_mask are applied.

commentstring

User-provided description.

Constraints: <= 65536 characters

configobject

Provider authentication, exposed models, request-forwarding controls, rate limits, and payload logging. Required on Create. On Update, it is required only when config or one of its subpaths appears in update_mask.

Show child attributesHide child attributes

provider_typestringImmutable

External model provider. Required on Create and immutable thereafter. Set the matching provider-specific configuration, such as openai, azure_openai, or amazon_bedrock.

Values:

• EXTERNAL_MODEL_PROVIDER_TYPE_OPENAI
• EXTERNAL_MODEL_PROVIDER_TYPE_AZURE_OPENAI
• EXTERNAL_MODEL_PROVIDER_TYPE_ANTHROPIC
• EXTERNAL_MODEL_PROVIDER_TYPE_AMAZON_BEDROCK
• EXTERNAL_MODEL_PROVIDER_TYPE_CUSTOM
• EXTERNAL_MODEL_PROVIDER_TYPE_MICROSOFT_FOUNDRY
• EXTERNAL_MODEL_PROVIDER_TYPE_GEMINI_ENTERPRISE

openaiobject

Show child attributesHide child attributes

directobject

OpenAI configuration with an API key supplied in the request.

Show child attributesHide child attributes

api_keyobject

OpenAI API key. Required when creating the service. Supply the value in api_key.plaintext.

organizationstring

Optional OpenAI organization ID. When set, the platform forwards it as the OpenAI-Organization header.

base_urlstring

Optional custom base URL. Defaults to https://api.openai.com/v1. Use for OpenAI-API-compatible third-party endpoints or in-network proxies.

azure_openaiobject

Show child attributesHide child attributes

directobject

Azure OpenAI endpoint and authentication configuration.

Show child attributesHide child attributes

base_urlstring

Full Azure OpenAI endpoint base URL, e.g. https://myresource.openai.azure.com. Required on Create.

api_keyobject

Azure OpenAI API key. Supply the value in api_key.plaintext. Mutually exclusive with Entra ID and Unity Catalog service credential authentication.

service_credentialobject

Reference to a Unity Catalog service credential authorizing Azure OpenAI requests. On Create, supply service_credential.name in the form credentials/{name}. Required on Create when using service-credential authentication; mutually exclusive with api_key and entra_service_principal. The credential is referenced by name; its value is not carried here. Only supported on Azure-hosted workspaces.

entra_service_principalobject

Entra ID service-principal authentication. Set tenant_id, client_id, and client_secret.plaintext. Mutually exclusive with api_key and service_credential.

anthropicobject

Show child attributesHide child attributes

directobject

Direct authentication with an API key supplied in direct.api_key.plaintext. Required unless relayed is set.

Show child attributesHide child attributes

api_keyobject

Anthropic API key. Required when creating the service. Supply the value in api_key.plaintext.

relayedobject

Relayed authentication. Each inference request supplies the caller's OAuth token, which is forwarded to Anthropic. No Anthropic credential is stored. Mutually exclusive with direct.

amazon_bedrockobject

Show child attributesHide child attributes

directobject

Amazon Bedrock region and authentication configuration.

Show child attributesHide child attributes

regionstring

AWS region where the Bedrock endpoint is hosted (e.g., us-east-1). Required on Create.

service_credentialobject

Reference to a Unity Catalog service credential authorizing Bedrock requests. On Create, supply service_credential.name in the form credentials/{name}. Required on Create when using service-credential authentication; mutually exclusive with aws_access_key. The credential is referenced by name; its value is not carried here. Only supported on AWS-hosted workspaces.

aws_access_keyobject

AWS access-key-pair authentication. Set access_key_id and secret_access_key.plaintext. Mutually exclusive with service_credential.

customobject

Show child attributesHide child attributes

directobject

Endpoint and authentication configuration for the custom provider.

Show child attributesHide child attributes

base_urlstring

Endpoint URL of the OpenAI-compatible service (e.g., https://api.example.com/v1). Required on Create.

api_keyobject

Bearer token forwarded in the Authorization header. Supply the value in api_key.plaintext.

microsoft_foundryobject

Show child attributesHide child attributes

directobject

Microsoft Foundry endpoint and authentication configuration.

Show child attributesHide child attributes

base_urlstring

Microsoft Foundry endpoint URL. Required on Create.

api_keyobject

Microsoft Foundry API key. Supply the value in api_key.plaintext. Mutually exclusive with Entra ID and Unity Catalog service credential authentication.

service_credentialobject

Reference to a Unity Catalog service credential authorizing Microsoft Foundry requests. On Create, supply service_credential.name in the form credentials/{name}. Required on Create when using service-credential authentication; mutually exclusive with api_key and entra_service_principal. The credential is referenced by name; its value is not carried here. Only supported on Azure-hosted workspaces.

entra_service_principalobject

Entra ID service-principal authentication. Set tenant_id, client_id, and client_secret.plaintext. Mutually exclusive with api_key and service_credential.

gemini_enterpriseobject

Show child attributesHide child attributes

directobject

Gemini Enterprise project, region, and authentication configuration.

Show child attributesHide child attributes

api_keyobject

Google Gemini Enterprise API key. Required when creating the service. Supply the value in api_key.plaintext.

project_idstring

GCP project ID hosting the Gemini Enterprise endpoint. Required on Create.

regionstring

GCP region of the Gemini Enterprise endpoint (e.g., us-central1). Required on Create.

allow_all_targetsboolean

When true, accepts any model exposed by the upstream provider; targets is not required and does not restrict routability. When false, only models listed in targets are routable. Defaults to false.

targetsarray of object

Models and provider-native API types exposed by this provider service. Each entry must include at least one native_api_types value. When allow_all_targets is false, at least one entry is required and model service destinations can reference only listed models. When allow_all_targets is true, any upstream model is routable; entries in this list provide API-type metadata without restricting other models.

Show child attributesHide child attributes

modelstringRequired

Provider-side model identifier, such as gpt-5 or claude-opus-4-7. This identifies a model at the upstream provider; it is not a Unity Catalog model resource.

native_api_typesarray of string

Provider-native API types supported by this model, such as openai/v1/chat/completions. At least one value is required. AI Gateway uses these values to translate requests and responses. At most 64 entries of 256 characters each are allowed.

forward_headersboolean

Whether to forward incoming HTTP headers to the upstream provider. Defaults to false and is configured for the entire provider service, not per request. Upstream authentication is configured separately in the provider-specific configuration.

forward_query_parametersboolean

Whether to forward incoming query parameters to the upstream provider. Defaults to false and is configured for the entire provider service, not per request.

forward_unmanaged_pathsboolean

Whether to proxy paths that AI Gateway does not recognize as configured provider-native API types. Defaults to false. When true, these paths are forwarded unchanged to the upstream provider. When false, only recognized API paths are served. Enabling this broadens the upstream API surface exposed through the provider service.

rate_limitsarray of object

Rate limits for requests sent directly to this provider service. Requests routed through a model service use that model service's rate limits instead.

Show child attributesHide child attributes

keystringRequired

Scope of the rate limit. Depending on this value, the limit applies to a principal, the service as a whole, or each user by default.

Values:

• RATE_LIMIT_KEY_USER
• RATE_LIMIT_KEY_USER_GROUP
• RATE_LIMIT_KEY_SERVICE_PRINCIPAL
• RATE_LIMIT_KEY_SERVICE
• RATE_LIMIT_KEY_USER_DEFAULT

renewal_periodstringRequired

Renewal period.

Values:

• RATE_LIMIT_RENEWAL_PERIOD_MINUTE
• RATE_LIMIT_RENEWAL_PERIOD_HOUR

principalstring

Principal this limit applies to: user email, group name, or service principal application ID. Required when key applies to a user, group, or service principal; otherwise it must be unset.

requestsint64

Maximum requests allowed in one renewal period. Leave unset for no request limit. Set to 0 to deny all requests.

tokensint64

Maximum tokens allowed in one renewal period. Leave unset for no token limit. Set to 0 to deny all requests.

inference_tableobject

Payload logging configuration for requests sent directly to this provider service. Requests routed through a model service are captured by that model service's inference table instead.

Show child attributesHide child attributes

parentstringRequired

Parent Unity Catalog schema where the inference table is created, in the form schemas/{catalog}.{schema}. Required when configuring an inference table. After the inference table is created, this field cannot be changed.

table_name_prefixstring

Prefix used to form the inference table's registered name. AI Gateway appends _payload; for example, table_name_prefix = "orders" creates orders_payload. If unset, the prefix defaults to the service name. Read table from the response for the resulting resource name. After the inference table is created, this field cannot be changed.

Response

Returns the ModelProviderService object.

View as Markdown

Request

{
  "comment": "string",
  "config": {
    "provider_type": "string",
    "openai": {},
    "azure_openai": {},
    "anthropic": {},
    "amazon_bedrock": {},
    "custom": {},
    "microsoft_foundry": {},
    "gemini_enterprise": {},
    "allow_all_targets": true,
    "targets": [
      {}
    ],
    "forward_headers": true,
    "forward_query_parameters": true,
    "forward_unmanaged_paths": true,
    "rate_limits": [
      {}
    ],
    "inference_table": {}
  }
}

Response

{
  "name": "string",
  "effective_owner": "string",
  "metastore_id": "string",
  "create_time": "string",
  "created_by": "string",
  "update_time": "string",
  "updated_by": "string",
  "comment": "string",
  "etag": "string",
  "config": {
    "provider_type": "string",
    "openai": {},
    "azure_openai": {},
    "anthropic": {},
    "amazon_bedrock": {},
    "custom": {},
    "microsoft_foundry": {},
    "gemini_enterprise": {},
    "allow_all_targets": true,
    "targets": [
      {}
    ],
    "forward_headers": true,
    "forward_query_parameters": true,
    "forward_unmanaged_paths": true,
    "rate_limits": [
      {}
    ],
    "inference_table": {}
  }
}

Delete a model provider service GA

DELETE /api/2.1/unity-catalog/{name=model-provider-services/*}

Deletes the model provider service identified by its resource name. Optionally supply an etag to make the delete conditional on the model provider service not having changed since it was read.

You must be the owner of the model provider service or have MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

API scopes: unity-catalog

Parameters

namestringRequiredpath

Resource name of the model provider service. Format: model-provider-services/{catalog}.{schema}.{model_provider_service}. Each {...} component is capped at 255 characters individually.

etagstringquery

Optimistic concurrency token from the most recent read. When set, the delete succeeds only if the resource has not changed. Leave unset for an unconditional delete. For REST requests, URL-encode the base64 string returned by the API when setting the etag query parameter.

View as Markdown

Response

{}