Unity Gateway quickstart

Send your first request through Unity Gateway against the OpenAI-compatible endpoint.

Requirements

• A Databricks workspace in a Unity Gateway supported region.
• To authenticate with OAuth, install the Databricks CLI. Alternatively, use a personal access token, which does not require the Databricks CLI.

Authenticate

To get started, use a personal access token. OAuth is recommended for production use cases. Set DATABRICKS_TOKEN to the token for your workspace.

Personal access token

Export a personal access token:

Bash

export DATABRICKS_TOKEN=<your-personal-access-token>

OAuth

Replace <workspace-url> with your Databricks workspace URL. Then log in with the Databricks CLI and export a short-lived OAuth token:

Bash

databricks auth login --host https://<workspace-url>
export DATABRICKS_TOKEN=$(databricks auth token --host https://<workspace-url> | jq -r .access_token)

Pick a model

Databricks provides ready-to-use models that you can browse in the UI under the system.ai schema, or see the complete list of supported models here.

This quickstart uses system.ai.gpt-5-2. To query a different model, swap in its fully qualified name.

Send your request

Replace <workspace-url> with your Databricks workspace URL.

Bash

Bash

curl https://<workspace-url>/ai-gateway/mlflow/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -d '{
    "model": "system.ai.gpt-5-2",
    "max_output_tokens": 256,
    "input": [
      {
        "role": "user",
        "content": [{"type": "input_text", "text": "Hello!"}]
      },
      {
        "role": "assistant",
        "content": [{"type": "output_text", "text": "Hello! How can I assist you today?"}]
      },
      {
        "role": "user",
        "content": [{"type": "input_text", "text": "What is Databricks?"}]
      }
    ]
  }'

Python

Python

from openai import OpenAI
import os

client = OpenAI(
  api_key=os.environ.get("DATABRICKS_TOKEN"),
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1",
)

response = client.responses.create(
  model="system.ai.gpt-5-2",
  max_output_tokens=256,
  input=[
    {"role": "user", "content": [{"type": "input_text", "text": "Hello!"}]},
    {"role": "assistant", "content": [{"type": "output_text", "text": "Hello! How can I assist you today?"}]},
    {"role": "user", "content": [{"type": "input_text", "text": "What is Databricks?"}]},
  ],
)

print(response.output)

TypeScript

TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.DATABRICKS_TOKEN,
  baseURL: 'https://<workspace-url>/ai-gateway/mlflow/v1',
});

const response = await client.responses.create({
  model: 'system.ai.gpt-5-2',
  max_output_tokens: 256,
  input: [
    { role: 'user', content: [{ type: 'input_text', text: 'Hello!' }] },
    { role: 'assistant', content: [{ type: 'output_text', text: 'Hello! How can I assist you today?' }] },
    { role: 'user', content: [{ type: 'input_text', text: 'What is Databricks?' }] },
  ],
});

console.log(response.output);

See your request

Open the model you queried (system.ai.gpt-5-2) in Catalog Explorer and select the Metrics tab to see the request you just sent in the usage history, along with its token usage and latency. See Unity Gateway observability.

Next steps

• Query foundation and embedding models
• Custom model endpoints
• Unity Gateway observability