Skip to main content

Overview

Databricks serves foundation models through two surfaces, both reachable under your workspace host and both OpenAI-compatible on the wire. Bifrost’s databricks provider covers both behind one provider, so you configure a workspace once and address models by name. Key characteristics:
  • One provider, two surfaces - the surface is chosen per request, by model name or by an explicit setting
  • OpenAI-compatible - Bifrost uses its shared OpenAI converters, so tool calling, structured outputs and streaming work unchanged
  • Responses API - works on every endpoint, so coding agents (Claude Code, Cursor, Codex CLI) work through Bifrost; served natively where the endpoint supports it and emulated through Chat Completions elsewhere
  • Reasoning on Claude - a reasoning_effort or reasoning budget is translated to the thinking object Claude endpoints take, and the reasoning they return is surfaced on the standard reasoning fields
  • Remote images - http(s) image URLs are fetched and inlined, since Claude endpoints on Databricks accept only inline image data
  • Two auth methods - a personal access token, or OAuth machine-to-machine with a service principal (Databricks’ production recommendation)
  • Governance tags - optionally forward Bifrost virtual key / team / customer names to Databricks usage tracking

Supported Operations

Custom MLflow models served at /serving-endpoints/{name}/invocations take a per-model input schema rather than a canonical chat or embedding request, so they are outside this provider’s scope. Use a custom provider with a request path override for those.

Prerequisites

  1. A Databricks workspace. Its URL looks like https://dbc-1234abcd-5678.cloud.databricks.com (AWS), https://adb-1234567890.azuredatabricks.net (Azure), or https://1234567890.gcp.databricks.com (GCP).
  2. Credentials, either:
    • a personal access token, from Settings > Developer > Access tokens; or
    • an OAuth M2M service principal client ID and secret, from Settings > Identity and access > Service principals. Databricks recommends this for production.
  3. Access to at least one model:
    • Model Serving: pay-per-token endpoints are preconfigured in most workspaces; availability varies by region.
    • Unity AI Gateway: every account user can query system.ai models with no setup. Querying a user-created model service needs USE CATALOG, USE SCHEMA and EXECUTE on it.

Setup & Configuration

  1. Navigate to Models > Model Providers. Look for Databricks under Configured Providers. If it is missing, click Add New Provider and select Databricks.
  2. Click Add Key or edit an existing key.
  3. Set a name for your key.
  4. Enter your Workspace URL directly or as an environment variable (for example, env.DATABRICKS_WORKSPACE_URL). A scheme and trailing slash are fine.
  5. Choose an Inference Surface. Leave it on Auto unless you want to pin one surface — see Choosing a surface.
  6. Pick an Authentication Method:
    • Personal Access Token - paste the token or use env.DATABRICKS_TOKEN.
    • OAuth M2M (Service Principal) - enter the client ID and secret. Leave the token blank. If the secret was created with scopes, list them under Scopes. See OAuth scopes.
  7. Optionally enable Forward Governance Tags to attribute usage on the Databricks side.
  8. Set Allowed Models to All Models (default) or a specific allowlist.
  9. Save the provider configuration.

Key configuration reference

A key needs either a value (personal access token) or both client_id and client_secret. Bifrost rejects a key that sets only one half of the service principal pair when you save it.

OAuth scopes

Bifrost asks for all-apis by default when it mints a token. A service principal secret created without scopes has all-apis, so most keys need nothing here. Databricks also lets an admin limit a secret to specific scopes when creating it, and the scopes can’t be changed afterwards. A token request that names any scope the secret lacks fails with a 403 like this one:
For a secret like that, set scopes to what the secret has. Bifrost sends them space-separated in the token request. A read-only scope such as all-apis:read can’t run inference, because querying a serving endpoint is a POST. Pick from the Databricks API scopes by what the key does: model-serving-inference doesn’t work for Bifrost. It only covers the per-endpoint /serving-endpoints/{name}/invocations path, which Bifrost doesn’t call, so Bifrost’s paths answer its token with Invalid scope, required scopes: model-serving. Model listing needs no scope. Bifrost lists Databricks models from its own catalog and never calls the workspace for them.
Bifrost doesn’t try other scopes on its own. If the token mints but doesn’t cover a call, for example a secret with only ai-gateway on a Model Serving request, Databricks rejects that call with Invalid scope, required scopes: ....

Choosing a surface

With api_format: "auto" (the default) the model name decides:
  • A catalog-qualified name — system.ai.claude-sonnet-4-5, or a <catalog>.<schema>.<service> Unity Catalog model service — routes to the Unity AI Gateway.
  • A databricks-* name — databricks-claude-sonnet-4-5 — is a pay-per-token endpoint and routes to Model Serving.
  • A model name that came from a key alias is sent exactly as configured; when it is bare it routes to Model Serving.
  • Any other bare name — gpt-5.5, claude-opus-5 — is treated as a short name for a ready-to-use system.ai model and routes to the Unity AI Gateway with the system.ai. prefix added (see below).
Set api_format explicitly to pin one surface. For production, an explicit setting is safer than relying on the naming convention. Provisioned-throughput endpoints with a custom name need api_format: "model_serving" or a key alias, since nothing in their name separates them from a short gateway name. Model aliases need no extra configuration: alias resolution rewrites the model to its upstream model_id before the provider sees it, so the surface is chosen from the upstream name.

Short names on the Unity AI Gateway

The AI Gateway addresses models by their full Unity Catalog name, but you do not have to spell out the system.ai catalog yourself. When a request targets the AI Gateway and the model name is not already catalog-qualified, Bifrost prefixes it with system.ai. before sending it upstream: A name counts as catalog-qualified when it has at least two dots, so a version dot such as the one in gpt-5.5 does not stop the prefix from being added. Names that come from a key alias are always sent exactly as the alias’s model_id, so an alias is the way to point a short name at a model service in a different catalog.

Usage

Reasoning on Claude endpoints

Claude endpoints on Databricks reject reasoning_effort and take Anthropic’s thinking object instead. Bifrost translates for you: a reasoning budget (reasoning.max_tokens) is sent as budget_tokens, an effort label is scaled to a budget the same way the Anthropic provider does, and models that only offer adaptive thinking get {"type": "adaptive"}. max_completion_tokens is raised above the budget when you have not set one, because the endpoint requires the ceiling to exceed the budget.
Every Databricks endpoint, Claude or not, returns reasoning as a content block ({"type": "reasoning", "summary": [...]}). Bifrost lifts it onto reasoning and reasoning_details (with the signature) on the message and on each streaming delta, so clients read it the same way as from any other provider. To speak the Databricks dialect directly, send thinking as a top-level field; Bifrost passes it through untouched and does not add its own.

Image inputs

Claude endpoints on Databricks accept only inline image data (Http data URLs are not supported by Claude). Bifrost fetches any http(s) image_url and sends it as a base64 data URL. The fetch uses the same SSRF-safe downloader as the Bedrock and Anthropic providers: only http/https, no private or loopback addresses, 25 MiB cap. A URL that cannot be fetched fails the request with a 400 rather than sending the model a request with the image silently removed.

Provider-specific parameters

Databricks accepts fields Bifrost does not model canonically, such as service_tier for priority pay-per-token inference. Send them as top-level fields and Bifrost forwards them:

Parameter support per model

Bifrost’s parameter set is wider than any single Databricks endpoint accepts, and both surfaces answer an unknown field with a 400 rather than ignoring it. Each optional parameter is therefore checked against the Bifrost datasheet record for the model behind the endpoint before the request goes out: A model the datasheet does not describe keeps every field except reasoning_effort and parallel_tool_calls — Databricks endpoint names are workspace-defined, so there is nothing to identify an unknown endpoint by, and a silent drop is worse than an upstream error you can read. parallel_tool_calls is the exception because both surfaces reject it outright; it is only sent when the datasheet row opts in. reasoning_effort resolves through unsupported_fields → supports_reasoning_effort (or a published effort ladder) → a reasoning_effort entry in the row’s parameters → the model reasons and is not Claude-family. Claude endpoints on Databricks reason through a thinking budget and reject an effort label, so it is translated to thinking there (see Reasoning on Claude endpoints). A requested effort is clamped onto the levels the model publishes. Anthropic-native fields — context_management, cache_control, speed, inference_geo, task_budget, container, mcp_servers — are always dropped, whatever the model. Both Databricks surfaces are OpenAI-shaped and reject them even on Claude endpoints.

Provisioned throughput

A provisioned-throughput endpoint uses the same request format as a pay-per-token one. Address it by its endpoint name on the Model Serving surface — no separate configuration.

Decisions

Two kinds of Databricks model answer /v1/decisions natively, neither of them a serving endpoint: the ai_decide AI Function and the System One models a workspace’s Unity Gateway serves.

ai_decide

Databricks’ ai_decide AI Function (Beta) is a workspace function rather than a serving endpoint, so address it as databricks/ai_decide:
Bifrost calls POST {workspace_url}/api/2.0/ai-functions/ai-decide with the key’s personal access token or service principal. The workspace needs the AI Functions preview enabled, and the token needs the ai-functions scope (or all-apis for OAuth). The body is TypeSafe’s System One format, so questions are converted as on TypeSafe. Differences from TypeSafe:
  • No model on the wire. ai_decide rejects a model field, so none is sent; the response reports ai_decide. Bifrost pins the function version with options.version: "1.0".
  • Text only. An input_image part is rejected by Bifrost with a 400; the function would otherwise read it as text. An empty input is also a 400, since ai_decide answers a null state with no answers.
  • Strict fields. An extra top-level or question field forwarded with x-bf-passthrough-extra-params comes back as Databricks’ 400 (Unexpected parameters).
  • Limits. Choice questions take 1-255 options and score questions 2-10 levels; every question needs instructions.
  • No usage or response id. Databricks’ x-request-id is in extra_fields.provider_response_headers, and a decision is priced at $0 unless you add a pricing override for the Decisions request type.

System One models

A workspace with Unity Catalog and Unity Gateway serves System One models, such as OpenJev and TypeSafe AI Jev, by their Unity Catalog name:
Bifrost calls POST {workspace_url}/ai-gateway/typesafe/v1/systemone with the key’s personal access token or service principal, which needs permission to execute the model service. The body and response are TypeSafe’s System One format, so questions are converted as on TypeSafe and the Unity Catalog name is sent as the model. Bifrost recognizes OpenJev and TypeSafe AI Jev models by their Unity Catalog names (system.ai.openjev-* and system.ai.typesafeai-jev-*, such as system.ai.typesafeai-jev-1-14-0); their serving endpoint names, such as databricks-openjev-qwen35-4b, are not accepted on this route. Another System One model service needs a model catalog entry with supports_decisions. TypeSafe AI Jev is hosted by TypeSafe and needs the account’s TypeSafe AI Models preview. Differences from TypeSafe:
  • Images by reference. An input_image part with an id reaches the model as TypeSafe assets, as on TypeSafe, and Bifrost adds the TypeSafe-Danger-Zone-Images: true header that Jev requires. Overriding it to unsupported in the provider’s Beta Headers settings, or setting network_config.beta_header_overrides to {"typesafe-danger-zone-images": false}, stops it. An inline input_image part without an id is rejected by Bifrost with a 400.
  • Errors. Databricks’ own errors pass through with their status, error_code, and message, such as a 422 for an invalid request or a 400 for an image the model rejects (Invalid image dimensions).
  • Reported model. The response names the model the gateway served, such as databricks-openjev-qwen35-4b or jev-1.14.0.
  • Usage. Input and output tokens are reported, images included, and a decision is priced from the model catalog, at $0 until it lists the model’s rates.
Any other Databricks model returns unsupported_operation for decisions; with convert_decision_to_responses on, it is emulated on the endpoint’s Responses API instead. A router can use ai_decide or a System One model as its classifier.

Usage attribution

With forward_gateway_tags enabled, Bifrost sends the resolved governance labels to Databricks on each request:
Databricks records these against the request for its own usage tracking, so Databricks-side cost reporting can be sliced the same way Bifrost’s is. Only display names are sent, never user identifiers. A tag header you supply yourself (via an x-bf-eh-databricks-ai-gateway-request-tags request header) takes precedence. Bifrost’s own telemetry is unaffected and remains the cross-provider view.

Cost tracking

Databricks pricing depends on the model, the serving configuration (pay-per-token vs provisioned throughput), the service tier, and cached-token behaviour. Bifrost prices Databricks requests from the model catalog rather than a flat provider rate. Databricks returns the standard OpenAI-shaped usage object, including reasoning_tokens and cache_read_input_tokens / cache_creation_input_tokens where the model supports them.

Troubleshooting

Legacy AI Gateway endpoints

Earlier Databricks workspaces expose a Beta-generation AI Gateway on a separate host, https://<workspace-id>.ai-gateway.cloud.databricks.com, with the MLflow surface at /mlflow/v1 rather than /ai-gateway/mlflow/v1. That host is not addressable by this provider’s base paths. To use it, configure a custom provider with base_provider_type: openai and a Base URL of https://<workspace-id>.ai-gateway.cloud.databricks.com/mlflow, keyless, with an Authorization: Bearer <PAT> extra header. For the native Anthropic Messages surface on that host, use a second custom provider with base_provider_type: anthropic and a Base URL of .../anthropic, with List Models disabled.