w.ai_gateway: AI Gateway

class databricks.sdk.service.catalog.AiGatewayAPI

Govern AI workloads in Unity Catalog. This API manages the Unity Catalog securables that bring centralized access control, lineage, and auditing to AI-serving entities: model services (governed access to foundation models and external LLMs), model provider services (governed resources for external model providers), and MCP services (governed Model Context Protocol servers).

create_mcp_service(mcp_service: McpService, parent: str, mcp_service_id: str) → McpService

Creates an MCP service in a Unity Catalog schema. An MCP (Model Context Protocol) service is a governed securable that registers an MCP server and exposes its tools for discovery, access control, and invocation. Specify its name in mcp_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. You also need USE_CONNECTION on the connection the MCP service references.

Parameters:

  • mcp_service – McpService The MCP service to create. Do not set name; the server derives it from parent and mcp_service_id. source_connection is required.

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

  • mcp_service_id – str Name for the MCP service, e.g. “my_mcp_service”.

Returns:

McpService

create_mcp_service_user_mapped_credential(name: str, login: McpServiceUserMappedCredentialLogin) → McpServiceUserMappedCredential

Logs the caller in to an MCP service: creates their per-user OAuth credential, or re-authenticates it if one already exists. The request body carries the OAuth exchange fields.

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

Parameters:
Returns:

McpServiceUserMappedCredential

create_model_provider_service(model_provider_service: ModelProviderService, parent: str, model_provider_service_id: str) → ModelProviderService

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

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

Parameters:

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

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

  • model_provider_service_id – str Name for the model provider service, e.g. “openai_prod”.

Returns:

ModelProviderService

create_model_service(model_service: ModelService, parent: str, model_service_id: str) → ModelService

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. Specify its 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. For every destination, you also need USE_CATALOG and USE_SCHEMA on its parent and EXECUTE on the referenced Unity Catalog model or model provider service. A provisioned-throughput destination additionally requires CAN_MANAGE on its Model Serving endpoint. Configuring an inference table additionally requires CREATE_TABLE.

Parameters:

  • model_service – ModelService The model service to create. Do not set name; the server derives it from parent and model_service_id.

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

  • model_service_id – str Name for the model service, e.g. “my_model_service”.

Returns:

ModelService

create_skill(skill: Skill, parent: str, skill_id: str) → Skill

Creates a skill in a Unity Catalog schema and provisions its managed bundle storage. Specify its name in skill_id. The request contains an optional comment but no bundle bytes. Upload bundle files through the Files API, then call FinalizeSkill.

You must be the owner of the parent schema or have CREATE_VOLUME and USE_SCHEMA on it, plus USE_CATALOG on the parent catalog.

Parameters:

  • skill – Skill The skill to create. comment is the only accepted client input and may be omitted. Do not set name; the server derives it from parent and skill_id.

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

  • skill_id – str Name for the skill, e.g. “basic-math”. The server normalizes this identifier to lowercase. It is independent of the bundle name read from SKILL.md.

Returns:

Skill

delete_mcp_service(name: str [, etag: Optional[str]])

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

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

Parameters:

  • name – str Resource name of the MCP service. Format: mcp-services/{catalog}.{schema}.{mcp_service}. Each {...} component is capped at 255 characters individually.

  • etag – str (optional) 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.

delete_mcp_service_user_mapped_credential(name: str) → DeleteMcpServiceUserMappedCredentialResponse

Revokes (deletes) the caller’s per-user OAuth credential for an MCP service (logout).

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

Parameters:

name – str Resource name of the MCP service. Format: mcp-services/{catalog}.{schema}.{mcp_service}.

Returns:

DeleteMcpServiceUserMappedCredentialResponse

delete_model_provider_service(name: str [, etag: Optional[str]])

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.

Parameters:

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

  • etag – str (optional) 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.

delete_model_service(name: str [, etag: Optional[str]])

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

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

Parameters:

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

  • etag – str (optional) 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.

delete_skill(name: str [, etag: Optional[str]])

Deletes the skill identified by its resource name and makes its managed bundle path unavailable. Managed bundle data is deleted asynchronously. Optionally supply an etag to make the delete conditional on the skill not having changed since it was read.

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

Parameters:

  • name – str Full resource name of the skill. Format: skills/{catalog}.{schema}.{skill}. Each {...} component is capped at 255 characters individually.

  • etag – str (optional) 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.

finalize_skill(name: str) → Skill

Finalizes a skill after its bundle is uploaded. This method reads SKILL.md through the Files API using the caller’s authorization. Its YAML frontmatter must contain an agentskills.io-compliant name and a nonblank description within the configured UTF-8 byte limit. On success, it replaces bundle_name and description; refreshes finalize_time, update_time, and updated_by; and returns the updated skill. comment is preserved. Re-finalization uses the latest SKILL.md and is last-write-wins without an etag precondition. Validation failures do not change metadata.

You must be the owner of the skill or have READ_VOLUME on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

Parameters:

name – str Full resource name of the skill. Format: skills/{catalog}.{schema}.{skill}. Each {...} component is capped at 255 characters individually.

Returns:

Skill

get_mcp_service(name: str) → McpService

Returns the MCP service identified by its resource name.

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

Parameters:

name – str Resource name of the MCP service. Format: mcp-services/{catalog}.{schema}.{mcp_service}. Each {...} component is capped at 255 characters individually.

Returns:

McpService

get_mcp_service_user_mapped_credential(name: str) → McpServiceUserMappedCredential

Returns the caller’s per-user OAuth login state for an MCP service. Read provisioning_info.state: ACTIVE means the caller is logged in and the credential is usable; any other state (for example a failed or still-provisioning login) means the login has not completed and the caller should log in again. If the caller has no credential yet, the RPC returns NOT_FOUND.

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

Parameters:

name – str Resource name of the MCP service. Format: mcp-services/{catalog}.{schema}.{mcp_service}.

Returns:

McpServiceUserMappedCredential

get_model_provider_service(name: str) → ModelProviderService

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.

Parameters:

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

Returns:

ModelProviderService

get_model_service(name: str) → ModelService

Returns the model service identified by its resource name.

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

Parameters:

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

Returns:

ModelService

get_skill(name: str) → Skill

Returns the skill identified by its resource name.

You must be the owner of the skill or have READ_VOLUME, READ_METADATA, or MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema.

Parameters:

name – str Full resource name of the skill. Format: skills/{catalog}.{schema}.{skill}. Each {...} component is capped at 255 characters individually.

Returns:

Skill

list_mcp_services([, page_size: Optional[int], page_token: Optional[str], parent: Optional[str], view: Optional[ListMcpServicesRequestView]]) → Iterator[McpService]

Lists the MCP 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 MCP services the caller can access (as owner or through EXECUTE, READ_METADATA, or MANAGE) are returned.

Parameters:

  • page_size – int (optional) Maximum number of MCP services to return. Defaults to 100 when unset or 0; the maximum is 200. Use page_token to retrieve additional pages.

  • page_token – str (optional) Opaque pagination token from the previous response.

  • parent – str (optional) Parent schema to list within, in the form schemas/{catalog}.{schema}. Required. Each {...} component is capped at 255 characters individually.

  • view – ListMcpServicesRequestView (optional) Fields to return for each service. FULL includes source-connection details and rate-limit principal names. BASIC omits the source connection and omits principal names from rate limits. Defaults to BASIC when unset.

Returns:

Iterator over McpService

list_model_provider_services([, page_size: Optional[int], page_token: Optional[str], parent: Optional[str], view: Optional[ListModelProviderServicesRequestView]]) → Iterator[ModelProviderService]

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.

Parameters:

  • page_size – int (optional) Maximum number of provider services to return. Defaults to 100 when unset or 0; the maximum is 200. Use page_token to retrieve additional pages.

  • page_token – str (optional) Opaque pagination token from the previous response.

  • parent – str (optional) Parent schema to list within, in the form schemas/{catalog}.{schema}. Required. Each {...} component is capped at 255 characters individually.

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

Returns:

Iterator over ModelProviderService

list_model_services([, page_size: Optional[int], page_token: Optional[str], parent: Optional[str], view: Optional[ListModelServicesRequestView]]) → Iterator[ModelService]

Lists the model 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 services the caller can access (as owner or through EXECUTE, READ_METADATA, or MANAGE) are returned.

Parameters:

  • page_size – int (optional) Maximum number of model services to return. Defaults to 100 when unset or 0; the maximum is 200. Use page_token to retrieve additional pages.

  • page_token – str (optional) Opaque pagination token from the previous response.

  • parent – str (optional) Parent schema to list within, in the form schemas/{catalog}.{schema}. Required. Each {...} component is capped at 255 characters individually.

  • view – ListModelServicesRequestView (optional) Fields to return for each service. FULL includes destinations, inference-table details, and rate-limit principal names. BASIC omits destinations and inference-table details and omits principal names from rate limits. Defaults to BASIC when unset.

Returns:

Iterator over ModelService

list_skills(parent: str [, page_size: Optional[int], page_token: Optional[str]]) → Iterator[Skill]

Lists skills 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 skills the caller can access as owner or through READ_VOLUME, READ_METADATA, or MANAGE are returned.

Parameters:

  • parent –

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

    Required: skill listing is schema-scoped, so parent must be set; an unset or empty parent is rejected with INVALID_PARAMETER_VALUE.

  • page_size – int (optional) Maximum number of skills to return. Defaults to 100 when unset or 0; the maximum is 200. Use page_token to retrieve additional pages.

  • page_token – str (optional) Opaque pagination token from a previous request.

Returns:

Iterator over Skill

update_mcp_service(name: str, mcp_service: McpService, update_mask: FieldMask [, etag: Optional[str]]) → McpService

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

You must be the owner of the MCP service or have MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema. When changing config.source_connection.name, the MCP service owner must also have USE_CONNECTION on the new connection.

Parameters:

  • name – str Resource name of the MCP service. Format: mcp-services/{catalog}.{schema}.{mcp_service}. Each {...} component is capped at 255 characters individually. Server-derived on Create from parent + mcp_service_id; required and immutable on Update/Get/Delete.

  • mcp_service – McpService The MCP service with the updated field values. name identifies the resource (mcp-services/{catalog}.{schema}.{mcp_service}); only fields listed in update_mask are applied.

  • update_mask – FieldMask 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.source_connection.name, config.include_tool_selectors, or config.rate_limits.

  • etag – str (optional) 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.

Returns:

McpService

update_model_provider_service(name: str, model_provider_service: ModelProviderService, update_mask: FieldMask [, etag: Optional[str]]) → ModelProviderService

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

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

Updating config.provider cannot change the provider type. Authentication mode changes require feature availability and support for both modes on the selected provider.

Parameters:

  • name – str 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.

  • model_provider_service – ModelProviderService 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.

  • update_mask – FieldMask Fields to update. Use config to replace the entire configuration. The replacement must include every required field; any optional field you omit is cleared. To preserve sibling fields, use one or more granular paths: comment; config.provider to replace the active provider-specific value (for example, config.openai; the mask path remains config.provider); config.allow_all_targets, config.targets, config.forward_headers, config.forward_query_parameters, config.forward_unmanaged_paths, config.rate_limits, config.pricing.default_discount_basis_points, or config.inference_table. For a pricing update, an explicitly empty pricing object clears the discount but retains the object; omitting pricing clears it. config.pricing is not a supported mask path. The provider type is immutable. A config or config.provider replacement that carries no authentication material preserves the existing authentication binding; input-only plaintext does not need to be read back and re-sent.

  • etag – str (optional) 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.

Returns:

ModelProviderService

update_model_service(name: str, model_service: ModelService, update_mask: FieldMask [, etag: Optional[str]]) → ModelService

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

You must be the owner of the model service or have MANAGE on it, plus USE_CATALOG on the parent catalog and USE_SCHEMA on the parent schema. When changing destinations, both you and the model service owner need USE_CATALOG and USE_SCHEMA on each destination’s parent and EXECUTE on the referenced Unity Catalog model or model provider service. A provisioned-throughput destination additionally requires CAN_MANAGE for you and CAN_QUERY for the model service owner. Adding an inference table additionally requires CREATE_TABLE.

Parameters:

  • name – str 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.

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

  • update_mask – FieldMask 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.routing.destinations, config.routing.fallback.destinations, config.rate_limits, or config.inference_table. Intermediate paths such as config.routing and config.routing.fallback are not supported.

  • etag – str (optional) 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.

Returns:

ModelService

update_skill(name: str, skill: Skill, update_mask: FieldMask [, etag: Optional[str]]) → Skill

Updates a skill. Only fields named in update_mask are changed; currently only comment is supported. The resource name is immutable. Optionally supply an etag to make the update conditional on the skill not having changed since it was read. Bundle files, grants, tags, and ownership are unchanged.

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

Parameters:

  • name – str Resource name of the skill. Format: skills/{catalog}.{schema}.{skill}. Each {...} component is capped at 255 characters individually. Server-derived on Create from parent + skill_id; required and immutable on Update/Get/Delete.

  • skill – Skill The skill with the updated field values. name identifies the resource (skills/{catalog}.{schema}.{skill}); only fields listed in update_mask are applied.

  • update_mask – FieldMask Fields to update; validated against skill. REQUIRED, matching the sibling Update RPCs. comment is the only mutable field.

  • etag – str (optional) 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.

Returns:

Skill