# Create

Launch stage: 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

## Query parameters

- `parent` (string, optional)
  Name of the parent schema.
   Format: `schemas/{catalog}.{schema}`.
   Each `{...}` component is capped at 255 characters individually.
- `model_provider_service_id` (string, optional)
  Name for the model provider service, e.g. "openai_prod".

## Request body

- `model_provider_service` (object, optional)
  The model provider service to create. The server populates `name` from
   `parent` + `model_provider_service_id`; clients should leave it unset.
  - `name` (string, optional)
    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.
  - `owner` (string, optional)
    The owner of the model provider service. Write-only; read owner via
     effective_owner.
  - `effective_owner` (string, optional)
    The resolved owner of the model provider service. Falls back to the
     caller's identity when `owner` is not explicitly set on creation.
  - `metastore_id` (string, optional)
    Metastore hosting the provider service.
  - `create_time` (string, optional)
    When the provider service was created.
  - `created_by` (string, optional)
    Creator identity.
  - `update_time` (string, optional)
    When the provider service was last modified.
  - `updated_by` (string, optional)
    Identity of the last updater.
  - `comment` (string, optional)
    User-provided description.
    Constraints: `<= 65536 characters`
  - `etag` (string, optional)
    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.
  - `config` (object, optional)
    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`.
    - `provider_type` (string, optional)
      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.
      Possible 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`
    - `openai` (object, required)
      - `direct` (object, required)
    - `azure_openai` (object, required)
      - `direct` (object, required)
    - `anthropic` (object, required)
      - `direct` (object, required)
        Direct (inline-credentials) form: caller supplies the API key in the
         request body. Required on Create unless `relayed` is set.
      - `relayed` (object, required)
        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_bedrock` (object, required)
      - `direct` (object, required)
    - `custom` (object, required)
      - `direct` (object, required)
    - `microsoft_foundry` (object, required)
      - `direct` (object, required)
    - `gemini_enterprise` (object, required)
      - `direct` (object, required)
    - `allow_all_targets` (boolean, optional)
      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.
    - `targets` (array of object, optional)
      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`.
      - `model` (string, optional)
        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_types` (array of string, optional)
        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_headers` (boolean, optional)
      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_parameters` (boolean, optional)
      Whether to forward incoming request query parameters to the upstream
       provider. Same trust-boundary semantics as `forward_headers`.
    - `forward_unmanaged_paths` (boolean, optional)
      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_limits` (array of object, optional)
      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`.
      - `key` (string, optional)
        Scope key. Determines whether `principal` is required.
        Possible 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_period` (string, optional)
        Renewal period.
        Possible values: `RATE_LIMIT_RENEWAL_PERIOD_MINUTE`, `RATE_LIMIT_RENEWAL_PERIOD_HOUR`
      - `principal` (string, optional)
        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).
      - `requests` (int64, optional)
        Max requests allowed within a renewal period. Leave unset for no request limit.
      - `tokens` (int64, optional)
        Max tokens allowed within a renewal period. Leave unset for no token limit.
      - `request_tag_key` (string, optional)
        Request tag key this limit applies to. Required when `key` is
         `RATE_LIMIT_KEY_REQUEST_TAG`, forbidden otherwise.
      - `request_tag_value` (string, optional)
        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_table` (object, optional)
      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`.
      - `parent` (string, optional)
        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_prefix` (string, optional)
        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.
      - `disabled` (boolean, optional)
        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.
      - `table` (string, optional)
        Resolved UC table for payload logs.
         Format: `tables/{catalog}.{schema}.{table}`.
      - `is_deleted` (boolean, optional)
        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.

## Returns

Returns the ModelProviderService object.

## Response

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