Model Provider Service

View as Markdown

A governed connection to an external model provider stored in Unity Catalog, such as an OpenAI account, Azure OpenAI deployment, or Amazon Bedrock account. It stores the provider type, authentication, and connection configuration used by model service destinations.

One ModelProviderService can back many ModelServices (e.g. an openai_prod provider serving multiple models); a single ModelService can fan out across multiple ModelProviderServices for traffic split 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/{model_provider_service.name=model-provider-services/*}Delete a model provider serviceDELETE /api/2.1/unity-catalog/{name=model-provider-services/*}

ModelProviderService object

A governed connection to an external model provider stored in Unity Catalog, such as an OpenAI account, Azure OpenAI deployment, or Amazon Bedrock account. It stores the provider type, authentication, and connection configuration used by model service destinations.

One ModelProviderService can back many ModelServices (e.g. an openai_prod provider serving multiple models); a single ModelService can fan out across multiple ModelProviderServices for traffic split or failover.

namestringBetaImmutable

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_ownerstringBetaOutput only

The resolved owner of the model provider service. Falls back to the caller's identity when owner is not explicitly set on creation.

metastore_idstringBetaOutput only

Metastore hosting the provider service.

create_timestringBetaOutput only

Time the provider service was created.

created_bystringBetaOutput only

Creator identity.

update_timestringBetaOutput only

Time the provider service was last modified.

updated_bystringBetaOutput only

Identity of the last updater.

commentstringBeta

User-provided description.

Constraints: <= 65536 characters

etagstringBetaOutput 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.

configobjectBeta

Provider connection, 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_typestringBetaImmutable

Provider type discriminator. Required at create time; immutable after. Determines which variant of the provider oneof must be set. May not be changed via Update; attempts to include config.provider_type in UpdateModelProviderServiceRequest.update_mask are rejected.

Required on CreateModelProviderService and immutable thereafter.

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

openaiobjectBeta

Show child attributesHide child attributes

directobjectBeta

Show child attributesHide child attributes

api_keyobjectBeta

OpenAI API key. Required on Create. Supplied as inline plaintext via ProviderSecret.plaintext.

organizationstringBeta

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

base_urlstringBeta

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

azure_openaiobjectBeta

Show child attributesHide child attributes

directobjectBeta

Show child attributesHide child attributes

base_urlstringBeta

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

api_keyobjectBeta

Azure OpenAI API key. Mutually exclusive with the Entra and service-credential modes. Supplied as inline plaintext via ProviderSecret.plaintext.

service_credentialobjectBeta

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. On read, the resolved id and is_deleted are also populated. Only supported on Azure-hosted workspaces; Create requests from other clouds are rejected with INVALID_PARAMETER_VALUE.

entra_service_principalobjectBeta

Entra ID (service principal) auth. Mutually exclusive with api_key and service_credential.

anthropicobjectBeta

Show child attributesHide child attributes

directobjectBeta

Direct (inline-credentials) form: caller supplies the API key in the request body. Required on Create unless relayed is set.

Show child attributesHide child attributes

api_keyobjectBeta

Anthropic API key. Required on Create. Sent as the x-api-key header on outbound requests. Supplied as inline plaintext via ProviderSecret.plaintext.

relayedobjectBeta

Relayed (credential-less) form: no Anthropic credential is stored. Each inference request instead carries the caller's own OAuth token, which the platform forwards to Anthropic on outbound requests. Mutually exclusive with direct; no api_key is required or persisted.

amazon_bedrockobjectBeta

Show child attributesHide child attributes

directobjectBeta

Show child attributesHide child attributes

regionstringBeta

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

service_credentialobjectBeta

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. On read, the resolved id and is_deleted are also populated. Only supported on AWS-hosted workspaces; Create requests from other clouds are rejected with INVALID_PARAMETER_VALUE.

aws_access_keyobjectBeta

AWS access-key-pair auth. Mutually exclusive with service_credential.

customobjectBeta

Show child attributesHide child attributes

directobjectBeta

Show child attributesHide child attributes

base_urlstringBeta

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

api_keyobjectBeta

Bearer token forwarded as the Authorization: Bearer ... header on outbound requests. Supplied as inline plaintext via ProviderSecret.plaintext. Set this for bearer-token auth.

microsoft_foundryobjectBeta

Show child attributesHide child attributes

directobjectBeta

Show child attributesHide child attributes

base_urlstringBeta

Microsoft Foundry endpoint URL. Required on Create.

api_keyobjectBeta

Microsoft Foundry API key. Mutually exclusive with the Entra and service-credential modes. Supplied as inline plaintext via ProviderSecret.plaintext.

service_credentialobjectBeta

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. On read, the resolved id and is_deleted are also populated. Only supported on Azure-hosted workspaces; Create requests from other clouds are rejected with INVALID_PARAMETER_VALUE.

entra_service_principalobjectBeta

Entra ID (service principal) auth. Mutually exclusive with api_key and service_credential.

gemini_enterpriseobjectBeta

Show child attributesHide child attributes

directobjectBeta

Show child attributesHide child attributes

api_keyobjectBeta

Google Gemini Enterprise API key. Required on Create when using API-key auth; mutually exclusive with service_credential. Supplied as inline plaintext via ProviderSecret.plaintext.

project_idstringBeta

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

regionstringBeta

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

allow_all_targetsbooleanBeta

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.

targetsarray of objectBeta

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

modelstringBeta

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 stringBeta

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

forward_headersbooleanBeta

Whether to forward incoming HTTP headers to the upstream provider. Applies to translated and passthrough requests and is configured for the entire provider service, not per request. Upstream authentication is configured separately in provider.

forward_query_parametersbooleanBeta

Whether incoming query parameters are forwarded to the upstream provider. Applies to translated and passthrough requests and is configured for the entire provider service, not per request.

forward_unmanaged_pathsbooleanBeta

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

rate_limitsarray of objectBeta

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

keystringBeta

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

Values: RATE_LIMIT_KEY_USER, RATE_LIMIT_KEY_USER_GROUP, RATE_LIMIT_KEY_SERVICE_PRINCIPAL, RATE_LIMIT_KEY_SERVICE, RATE_LIMIT_KEY_USER_DEFAULT, RATE_LIMIT_KEY_REQUEST_TAG

renewal_periodstringBeta

Renewal period.

Values: RATE_LIMIT_RENEWAL_PERIOD_MINUTE, RATE_LIMIT_RENEWAL_PERIOD_HOUR

principalstringBeta

Principal this limit applies to: user email, group name, or service principal application ID. Required unless key is RATE_LIMIT_KEY_SERVICE, RATE_LIMIT_KEY_USER_DEFAULT, or RATE_LIMIT_KEY_REQUEST_TAG (which must not set a principal).

requestsint64Beta

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

tokensint64Beta

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

request_tag_keystringBeta

Request tag key this limit applies to. Required when key is RATE_LIMIT_KEY_REQUEST_TAG, forbidden otherwise.

request_tag_valuestringBeta

Request tag value this limit applies to. Only valid when key is RATE_LIMIT_KEY_REQUEST_TAG. Leave unset to apply the limit to every value of request_tag_key (an any-value default); a set value is a specific override for that value.

inference_tableobjectBeta

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

parentstringBeta

Parent UC schema where the inference table is created. Format: schemas/{catalog}.{schema}. Set at create time and immutable thereafter; changing it on an existing service is rejected.

table_name_prefixstringBeta

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 resolved resource name. Set at create time and immutable thereafter.

tablestringBetaOutput only

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

is_deletedbooleanBetaOutput only

True when the bound inference TABLE has been deleted but the parent service still references it. The dangling reference is surfaced (not silently dropped) so callers can see the broken dependency. AI Gateway payload logging fails closed in this state.

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 Beta

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 Beta

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 a previous request.

viewstringquery

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

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 Beta

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

Creates a model provider service in a Unity Catalog schema. A model provider service is a governed connection to an external model provider (for example OpenAI, Azure OpenAI, or Amazon Bedrock) that model services reference to invoke that provider. The caller supplies the leaf 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.

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

model_provider_serviceobjectRequired

The model provider service to create. The server populates name from parent + model_provider_service_id; clients should leave it unset.

Show child attributesHide child attributes

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 connection, 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

Provider type discriminator. Required at create time; immutable after. Determines which variant of the provider oneof must be set. May not be changed via Update; attempts to include config.provider_type in UpdateModelProviderServiceRequest.update_mask are rejected.

Required on CreateModelProviderService and immutable thereafter.

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

azure_openaiobject

Show child attributesHide child attributes

directobject

anthropicobject

Show child attributesHide child attributes

directobject

Direct (inline-credentials) form: caller supplies the API key in the request body. Required on Create unless relayed is set.

relayedobject

Relayed (credential-less) form: no Anthropic credential is stored. Each inference request instead carries the caller's own OAuth token, which the platform forwards to Anthropic on outbound requests. Mutually exclusive with direct; no api_key is required or persisted.

amazon_bedrockobject

Show child attributesHide child attributes

directobject

customobject

Show child attributesHide child attributes

directobject

microsoft_foundryobject

Show child attributesHide child attributes

directobject

gemini_enterpriseobject

Show child attributesHide child attributes

directobject

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.

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. 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. Applies to translated and passthrough requests and is configured for the entire provider service, not per request. Upstream authentication is configured separately in provider.

forward_query_parametersboolean

Whether incoming query parameters are forwarded to the upstream provider. Applies to translated and passthrough requests 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. When true, these paths are forwarded unchanged over the provider connection. 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, each user by default, or a request tag.

Values: RATE_LIMIT_KEY_USER, RATE_LIMIT_KEY_USER_GROUP, RATE_LIMIT_KEY_SERVICE_PRINCIPAL, RATE_LIMIT_KEY_SERVICE, RATE_LIMIT_KEY_USER_DEFAULT, RATE_LIMIT_KEY_REQUEST_TAG

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 unless key is RATE_LIMIT_KEY_SERVICE, RATE_LIMIT_KEY_USER_DEFAULT, or RATE_LIMIT_KEY_REQUEST_TAG (which must not set a principal).

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.

request_tag_keystring

Request tag key this limit applies to. Required when key is RATE_LIMIT_KEY_REQUEST_TAG, forbidden otherwise.

request_tag_valuestring

Request tag value this limit applies to. Only valid when key is RATE_LIMIT_KEY_REQUEST_TAG. Leave unset to apply the limit to every value of request_tag_key (an any-value default); a set value is a specific override for that value.

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 UC schema where the inference table is created. Format: schemas/{catalog}.{schema}. Set at create time and immutable thereafter; changing it on an existing service is rejected.

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 resolved resource name. Set at create time and immutable thereafter.

Response

Returns the ModelProviderService object.

View as Markdown

Request

{
  "model_provider_service": {
    "name": "string",
    "comment": "string",
    "config": {}
  }
}

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 Beta

PATCH /api/2.1/unity-catalog/{model_provider_service.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.

API scopes: unity-catalog

Parameters

model_provider_serviceobjectRequiredpath

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.

Show child attributesHide child attributes

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 connection, 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

Provider type discriminator. Required at create time; immutable after. Determines which variant of the provider oneof must be set. May not be changed via Update; attempts to include config.provider_type in UpdateModelProviderServiceRequest.update_mask are rejected.

Required on CreateModelProviderService and immutable thereafter.

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

azure_openaiobject

Show child attributesHide child attributes

directobject

anthropicobject

Show child attributesHide child attributes

directobject

Direct (inline-credentials) form: caller supplies the API key in the request body. Required on Create unless relayed is set.

relayedobject

Relayed (credential-less) form: no Anthropic credential is stored. Each inference request instead carries the caller's own OAuth token, which the platform forwards to Anthropic on outbound requests. Mutually exclusive with direct; no api_key is required or persisted.

amazon_bedrockobject

Show child attributesHide child attributes

directobject

customobject

Show child attributesHide child attributes

directobject

microsoft_foundryobject

Show child attributesHide child attributes

directobject

gemini_enterpriseobject

Show child attributesHide child attributes

directobject

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.

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. 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. Applies to translated and passthrough requests and is configured for the entire provider service, not per request. Upstream authentication is configured separately in provider.

forward_query_parametersboolean

Whether incoming query parameters are forwarded to the upstream provider. Applies to translated and passthrough requests 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. When true, these paths are forwarded unchanged over the provider connection. 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, each user by default, or a request tag.

Values: RATE_LIMIT_KEY_USER, RATE_LIMIT_KEY_USER_GROUP, RATE_LIMIT_KEY_SERVICE_PRINCIPAL, RATE_LIMIT_KEY_SERVICE, RATE_LIMIT_KEY_USER_DEFAULT, RATE_LIMIT_KEY_REQUEST_TAG

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 unless key is RATE_LIMIT_KEY_SERVICE, RATE_LIMIT_KEY_USER_DEFAULT, or RATE_LIMIT_KEY_REQUEST_TAG (which must not set a principal).

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.

request_tag_keystring

Request tag key this limit applies to. Required when key is RATE_LIMIT_KEY_REQUEST_TAG, forbidden otherwise.

request_tag_valuestring

Request tag value this limit applies to. Only valid when key is RATE_LIMIT_KEY_REQUEST_TAG. Leave unset to apply the limit to every value of request_tag_key (an any-value default); a set value is a specific override for that value.

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 UC schema where the inference table is created. Format: schemas/{catalog}.{schema}. Set at create time and immutable thereafter; changing it on an existing service is rejected.

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 resolved resource name. Set at create time and immutable thereafter.

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, 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.

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": {}
  }
}

Delete a model provider service Beta

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

{}