Model Provider Service

View as Markdown

A governed external model-provider connection stored in Unity Catalog (e.g. an OpenAI API account, an Azure OpenAI deployment, an Amazon Bedrock account). Owns the provider type and the auth/configuration the platform needs to invoke that provider, and is referenced from ExternalModelConfig.model_provider_service on a ModelService.

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.

GetGET /api/2.1/unity-catalog/{name=model-provider-services/*}ListGET /api/2.1/unity-catalog/model-provider-servicesCreatePOST /api/2.1/unity-catalog/model-provider-servicesUpdatePATCH /api/2.1/unity-catalog/{model_provider_service.name=model-provider-services/*}DeleteDELETE /api/2.1/unity-catalog/{name=model-provider-services/*}

ModelProviderService object

A governed external model-provider connection stored in Unity Catalog (e.g. an OpenAI API account, an Azure OpenAI deployment, an Amazon Bedrock account). Owns the provider type and the auth/configuration the platform needs to invoke that provider, and is referenced from ExternalModelConfig.model_provider_service on a ModelService.

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.

namestringBeta

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.

ownerstringBeta

The owner of the model provider service. Write-only; read owner via effective_owner.

effective_ownerstringBeta

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

metastore_idstringBeta

Metastore hosting the provider service.

create_timestringBeta

When the provider service was created.

created_bystringBeta

Creator identity.

update_timestringBeta

When the provider service was last modified.

updated_bystringBeta

Identity of the last updater.

commentstringBeta

User-provided description.

Constraints: <= 65536 characters

etagstringBeta

Optimistic concurrency control token. Server-generated from the entity's state and returned on every read. To use it as an if-match precondition on a mutation, echo the last-read value back via the dedicated etag field on the Update / Delete request; the server rejects the mutation if the stored etag differs.

configobjectBeta

Behavioral configuration: provider connection, model catalog, and passthrough policy. See ModelProviderServiceConfig for the per-field contract. Required on CreateModelProviderService; on Update it is required only when config (or a config.* subpath) appears in update_mask.

Show child attributesHide child attributes

provider_typestringBeta

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 UC service credential authorizing Azure OpenAI requests. On Create the caller supplies service_credential.name in the AIP-122 resource-name form credentials/{name}. Required on Create when using UC-service-credential auth; 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.

Show child attributesHide child attributes

plan_typestringBeta

Which Anthropic subscription tier the relayed token belongs to. Optional; when unset the MPS gets the full governance surface (see TEAM_ENTERPRISE). Immutable after Create, so the tier cannot be flipped in place.

Values: ANTHROPIC_RELAYED_PLAN_TYPE_MAX, ANTHROPIC_RELAYED_PLAN_TYPE_TEAM_ENTERPRISE

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 UC service credential authorizing Bedrock requests. On Create the caller supplies service_credential.name in the AIP-122 resource-name form credentials/{name}. Required on Create when using UC-service-credential auth; 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 AI Foundry endpoint URL. Required on Create.

api_keyobjectBeta

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

service_credentialobjectBeta

Reference to a UC service credential authorizing Microsoft Foundry requests. On Create the caller supplies service_credential.name in the AIP-122 resource-name form credentials/{name}. Required on Create when using UC-service-credential auth; 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

Routing targets this provider service exposes (provider-side model identifier + unified API types per entry). Required (>=1) when allow_all_targets = false; optional and additive when allow_all_targets = true. References from ExternalModelConfig.target must match an entry here unless allow_all_targets = true.

Show child attributesHide child attributes

modelstringBeta

Provider-side model identifier (e.g. "gpt-5", "claude-opus-4-7"). This is a string on the LLM provider's side, not a UC entity. The UC governance hook for external destinations is the ModelProviderService referenced by ExternalModelConfig.model_provider_service, not the model itself.

native_api_typesarray of stringBeta

Provider-native API types the model supports (e.g. "openai/v1/chat/completions"). Used by the platform for request/response translation from the unified API type. At most 64 entries of at most 256 characters each; the list is persisted into the destination binding's bounded storage envelope.

forward_headersbooleanBeta

Whether to forward incoming request headers to the upstream provider. Applies to managed (multi-model) requests as well as passthrough requests served by this provider service. Governance-level decision by the provider service owner; not selectable per inference call.

forward_query_parametersbooleanBeta

Whether to forward incoming request query parameters to the upstream provider. Same trust-boundary semantics as forward_headers.

forward_unmanaged_pathsbooleanBeta

Whether to forward request paths that fall outside this service's managed API set to the upstream provider as opaque passthrough. When true, requests addressed to subpaths not recognized by the managed API surface are proxied to the upstream provider over the same provider connection. When false, only managed-API paths are served. Governance-level decision by the provider service owner; expanding this expands the trust boundary that the ModelProviderService exposes.

rate_limitsarray of objectBeta

Rate limits applied when this provider service is invoked directly. When it is invoked through a model service, the model service's own rate_limits apply instead. Mirrors ModelServiceConfig.rate_limits / McpServiceConfig.rate_limits.

Show child attributesHide child attributes

keystringBeta

Scope key. Determines whether principal is required.

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

Max requests allowed within a renewal period. Leave unset for no request limit.

tokensint64Beta

Max tokens allowed within a renewal period. Leave unset for no token limit.

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

Inference table configuration for payload logging when this provider service is invoked directly. When it is invoked through a model service, the model service's own inference table captures the invocation instead. Mirrors ModelServiceConfig.inference_table / AgentServiceConfig.inference_table.

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 for the inference-table's UC-registered name. The actual leaf name UC stores is <table_name_prefix>_payload; the _payload suffix is appended automatically. To find the actual UC table after Create, read the table field on the response. Defaults to <model_service_name>_payload when unset. Set at create time and immutable thereafter; changing it on an existing service is rejected.

disabledbooleanBeta

Indicates whether payload logging is disabled (opt-out). Unset means that payload logging is active (the on-by-default state coincides with the proto zero-value, so the server never fills this field for a client that leaves it unset). Set disabled = true to pause runtime logging while keeping the sub-message attached (preserving parent and table_name_prefix for a later flip back to active). parent remains required either way.

tablestringBeta

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

is_deletedbooleanBeta

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",
  "owner": "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 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

namestringpath

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",
  "owner": "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 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

Name of the parent schema to list within, as schemas/{catalog}.{schema}. 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

View selector controlling which fields are populated per row. FULL returns the full representation of the service; BASIC returns a more compact version. 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",
      "owner": "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 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

parentstringquery

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

model_provider_service_idstringquery

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

Request body

model_provider_serviceobject

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

namestring

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.

ownerstring

The owner of the model provider service. Write-only; read owner via effective_owner.

effective_ownerstring

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

metastore_idstring

Metastore hosting the provider service.

create_timestring

When the provider service was created.

created_bystring

Creator identity.

update_timestring

When the provider service was last modified.

updated_bystring

Identity of the last updater.

commentstring

User-provided description.

Constraints: <= 65536 characters

etagstring

Optimistic concurrency control token. Server-generated from the entity's state and returned on every read. To use it as an if-match precondition on a mutation, echo the last-read value back via the dedicated etag field on the Update / Delete request; the server rejects the mutation if the stored etag differs.

configobject

Behavioral configuration: provider connection, model catalog, and passthrough policy. See ModelProviderServiceConfig for the per-field contract. Required on CreateModelProviderService; on Update it is required only when config (or a config.* subpath) appears in update_mask.

Show child attributesHide child attributes

provider_typestring

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

openaiobjectRequired

Show child attributesHide child attributes

directobjectRequired

azure_openaiobjectRequired

Show child attributesHide child attributes

directobjectRequired

anthropicobjectRequired

Show child attributesHide child attributes

directobjectRequired

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

relayedobjectRequired

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_bedrockobjectRequired

Show child attributesHide child attributes

directobjectRequired

customobjectRequired

Show child attributesHide child attributes

directobjectRequired

microsoft_foundryobjectRequired

Show child attributesHide child attributes

directobjectRequired

gemini_enterpriseobjectRequired

Show child attributesHide child attributes

directobjectRequired

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

Routing targets this provider service exposes (provider-side model identifier + unified API types per entry). Required (>=1) when allow_all_targets = false; optional and additive when allow_all_targets = true. References from ExternalModelConfig.target must match an entry here unless allow_all_targets = true.

Show child attributesHide child attributes

modelstring

Provider-side model identifier (e.g. "gpt-5", "claude-opus-4-7"). This is a string on the LLM provider's side, not a UC entity. The UC governance hook for external destinations is the ModelProviderService referenced by ExternalModelConfig.model_provider_service, not the model itself.

native_api_typesarray of string

Provider-native API types the model supports (e.g. "openai/v1/chat/completions"). Used by the platform for request/response translation from the unified API type. At most 64 entries of at most 256 characters each; the list is persisted into the destination binding's bounded storage envelope.

forward_headersboolean

Whether to forward incoming request headers to the upstream provider. Applies to managed (multi-model) requests as well as passthrough requests served by this provider service. Governance-level decision by the provider service owner; not selectable per inference call.

forward_query_parametersboolean

Whether to forward incoming request query parameters to the upstream provider. Same trust-boundary semantics as forward_headers.

forward_unmanaged_pathsboolean

Whether to forward request paths that fall outside this service's managed API set to the upstream provider as opaque passthrough. When true, requests addressed to subpaths not recognized by the managed API surface are proxied to the upstream provider over the same provider connection. When false, only managed-API paths are served. Governance-level decision by the provider service owner; expanding this expands the trust boundary that the ModelProviderService exposes.

rate_limitsarray of object

Rate limits applied when this provider service is invoked directly. When it is invoked through a model service, the model service's own rate_limits apply instead. Mirrors ModelServiceConfig.rate_limits / McpServiceConfig.rate_limits.

Show child attributesHide child attributes

keystring

Scope key. Determines whether principal is required.

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_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 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

Max requests allowed within a renewal period. Leave unset for no request limit.

tokensint64

Max tokens allowed within a renewal period. Leave unset for no token limit.

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

Inference table configuration for payload logging when this provider service is invoked directly. When it is invoked through a model service, the model service's own inference table captures the invocation instead. Mirrors ModelServiceConfig.inference_table / AgentServiceConfig.inference_table.

Show child attributesHide child attributes

parentstring

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 for the inference-table's UC-registered name. The actual leaf name UC stores is <table_name_prefix>_payload; the _payload suffix is appended automatically. To find the actual UC table after Create, read the table field on the response. Defaults to <model_service_name>_payload when unset. Set at create time and immutable thereafter; changing it on an existing service is rejected.

disabledboolean

Indicates whether payload logging is disabled (opt-out). Unset means that payload logging is active (the on-by-default state coincides with the proto zero-value, so the server never fills this field for a client that leaves it unset). Set disabled = true to pause runtime logging while keeping the sub-message attached (preserving parent and table_name_prefix for a later flip back to active). parent remains required either way.

tablestring

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

is_deletedboolean

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.

Response

Returns the ModelProviderService object.

View as Markdown

Request

{
  "model_provider_service": {
    "name": "string",
    "owner": "string",
    "effective_owner": "string",
    "metastore_id": "string",
    "create_time": "string",
    "created_by": "string",
    "update_time": "string",
    "updated_by": "string",
    "comment": "string",
    "etag": "string",
    "config": {}
  }
}

Response

{
  "name": "string",
  "owner": "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 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_serviceobjectpath

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

namestring

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.

ownerstring

The owner of the model provider service. Write-only; read owner via effective_owner.

effective_ownerstring

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

metastore_idstring

Metastore hosting the provider service.

create_timestring

When the provider service was created.

created_bystring

Creator identity.

update_timestring

When the provider service was last modified.

updated_bystring

Identity of the last updater.

commentstring

User-provided description.

Constraints: <= 65536 characters

etagstring

Optimistic concurrency control token. Server-generated from the entity's state and returned on every read. To use it as an if-match precondition on a mutation, echo the last-read value back via the dedicated etag field on the Update / Delete request; the server rejects the mutation if the stored etag differs.

configobject

Behavioral configuration: provider connection, model catalog, and passthrough policy. See ModelProviderServiceConfig for the per-field contract. Required on CreateModelProviderService; on Update it is required only when config (or a config.* subpath) appears in update_mask.

Show child attributesHide child attributes

provider_typestring

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

openaiobjectRequired

Show child attributesHide child attributes

directobjectRequired

azure_openaiobjectRequired

Show child attributesHide child attributes

directobjectRequired

anthropicobjectRequired

Show child attributesHide child attributes

directobjectRequired

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

relayedobjectRequired

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_bedrockobjectRequired

Show child attributesHide child attributes

directobjectRequired

customobjectRequired

Show child attributesHide child attributes

directobjectRequired

microsoft_foundryobjectRequired

Show child attributesHide child attributes

directobjectRequired

gemini_enterpriseobjectRequired

Show child attributesHide child attributes

directobjectRequired

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

Routing targets this provider service exposes (provider-side model identifier + unified API types per entry). Required (>=1) when allow_all_targets = false; optional and additive when allow_all_targets = true. References from ExternalModelConfig.target must match an entry here unless allow_all_targets = true.

Show child attributesHide child attributes

modelstring

Provider-side model identifier (e.g. "gpt-5", "claude-opus-4-7"). This is a string on the LLM provider's side, not a UC entity. The UC governance hook for external destinations is the ModelProviderService referenced by ExternalModelConfig.model_provider_service, not the model itself.

native_api_typesarray of string

Provider-native API types the model supports (e.g. "openai/v1/chat/completions"). Used by the platform for request/response translation from the unified API type. At most 64 entries of at most 256 characters each; the list is persisted into the destination binding's bounded storage envelope.

forward_headersboolean

Whether to forward incoming request headers to the upstream provider. Applies to managed (multi-model) requests as well as passthrough requests served by this provider service. Governance-level decision by the provider service owner; not selectable per inference call.

forward_query_parametersboolean

Whether to forward incoming request query parameters to the upstream provider. Same trust-boundary semantics as forward_headers.

forward_unmanaged_pathsboolean

Whether to forward request paths that fall outside this service's managed API set to the upstream provider as opaque passthrough. When true, requests addressed to subpaths not recognized by the managed API surface are proxied to the upstream provider over the same provider connection. When false, only managed-API paths are served. Governance-level decision by the provider service owner; expanding this expands the trust boundary that the ModelProviderService exposes.

rate_limitsarray of object

Rate limits applied when this provider service is invoked directly. When it is invoked through a model service, the model service's own rate_limits apply instead. Mirrors ModelServiceConfig.rate_limits / McpServiceConfig.rate_limits.

Show child attributesHide child attributes

keystring

Scope key. Determines whether principal is required.

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_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 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

Max requests allowed within a renewal period. Leave unset for no request limit.

tokensint64

Max tokens allowed within a renewal period. Leave unset for no token limit.

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

Inference table configuration for payload logging when this provider service is invoked directly. When it is invoked through a model service, the model service's own inference table captures the invocation instead. Mirrors ModelServiceConfig.inference_table / AgentServiceConfig.inference_table.

Show child attributesHide child attributes

parentstring

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 for the inference-table's UC-registered name. The actual leaf name UC stores is <table_name_prefix>_payload; the _payload suffix is appended automatically. To find the actual UC table after Create, read the table field on the response. Defaults to <model_service_name>_payload when unset. Set at create time and immutable thereafter; changing it on an existing service is rejected.

disabledboolean

Indicates whether payload logging is disabled (opt-out). Unset means that payload logging is active (the on-by-default state coincides with the proto zero-value, so the server never fills this field for a client that leaves it unset). Set disabled = true to pause runtime logging while keeping the sub-message attached (preserving parent and table_name_prefix for a later flip back to active). parent remains required either way.

tablestring

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

is_deletedboolean

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.

update_maskstringquery

The list of fields to update. The framework validates each path against the model_provider_service field above. Wildcard paths (paths: ["*"]) are not supported; list each field path explicitly.

etagstringquery

If-match precondition: when set, the update proceeds only if the current server-side etag matches. Empty means an unconditional update.

Response

Returns the ModelProviderService object.

View as Markdown

Response

{
  "name": "string",
  "owner": "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 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

namestringpath

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

If-match precondition: when set, the delete proceeds only if the current server-side etag matches. Empty means unconditional delete.

View as Markdown

Response

{}