# Create

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

Creates a model service in a Unity Catalog schema. A model service is a
 governed AI Gateway endpoint that routes inference requests to one or more
 model destinations. The caller supplies the leaf name in
 `model_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_service_id` (string, optional)
  Name for the model service, e.g. "my_model_service".

## Request body

- `model_service` (object, optional)
  The model service to create. The server populates `name` from `parent` +
   `model_service_id`; clients should leave it unset.
  - `name` (string, optional)
    Resource name of the model service.
     Format: `model-services/{catalog}.{schema}.{model_service}`.
     Each `{...}` component is capped at 255 characters individually.
      Server-derived on Create from `parent` +
     `model_service_id`; required and immutable on Update/Get/Delete.
  - `owner` (string, optional)
    The owner of the model service. Write-only; read owner via effective_owner.
  - `effective_owner` (string, optional)
    The resolved owner of the ModelService. Falls back to the caller's identity
     when `owner` is not explicitly set on creation.
  - `metastore_id` (string, optional)
    Metastore hosting the model service.
  - `create_time` (string, optional)
    When the model service was created.
  - `created_by` (string, optional)
    Creator identity.
  - `update_time` (string, optional)
    When the model service was last modified.
  - `updated_by` (string, optional)
    Identity of the last updater.
  - `comment` (string, optional)
    User-provided description.
    Constraints: `<= 65536 characters`
  - `config` (object, optional)
    Operational configuration: destinations, routing, rate limits, inference
     table. Required on CreateModelService; on UpdateModelService it is
     required only when `config` (or a `config.*` subpath) appears in
     `update_mask`.
    - `routing` (object, optional)
      Routing configuration: destinations, routing strategy, and fallback.
      - `destinations` (array of object, optional)
        Primary routing destinations. At most 10 are allowed. At least one is
         required on CreateModelService; on UpdateModelService it is required only
         when `config.routing` (or a `config.routing.*` subpath) appears in
         `update_mask`.
      - `traffic_splitting` (object, required)
        Marker message selecting request-based traffic splitting. Traffic is
         distributed according to each destination's traffic_percentage value;
         no configuration lives on this message itself.
      - `fallback` (object, optional)
        Fallback routing config, applied after primary destinations fail.
      - `first_token_timeout` (string, optional)
        Timeout for the first token of a streaming response. If a destination does
         not return its first token within this duration, AI Gateway aborts the
         attempt and fails over to the next destination. Applies to streaming
         requests only. Leave unset for no first-token timeout.
    - `rate_limits` (array of object, optional)
      Rate limits applied to requests routed through this model service.
      - `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 config for payload logging.
      - `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.
  - `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.
  - `supported_api_types` (array of string, optional)
    Unified API types this endpoint supports (e.g. "chat", "embeddings",
     "completions"). Derived from the destinations' backing models / providers
     at read time.

## Returns

Returns the ModelService 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",
  "config": {
    "routing": {},
    "rate_limits": [
      {}
    ],
    "inference_table": {}
  },
  "etag": "string",
  "supported_api_types": [
    "string"
  ]
}
```