The Databricks Workspace API allows you to list, import, export, and delete notebooks, folders, and libraries in a Databricks workspace. It provides programmatic access to manage workspace objects, enabling automation of notebook deployment and workspace organization.
openapi: 3.1.0
info:
title: Databricks REST API
description: >-
The Databricks REST API provides programmatic access to manage Databricks
workspace resources including clusters, jobs, and workspace objects. All API
endpoints require authentication using a personal access token or OAuth token
passed via the Authorization header. The base URL is specific to your
Databricks workspace deployment region.
version: 2.1.0
contact:
name: Databricks
url: https://www.databricks.com/company/contact
email: [email protected]
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
termsOfService: https://www.databricks.com/legal/terms-of-use
servers:
- url: https://{workspace_host}/api
description: Databricks workspace API endpoint
variables:
workspace_host:
default: adb-1234567890123456.7.azuredatabricks.net
description: >-
The hostname of your Databricks workspace. Format varies by cloud
provider (e.g., adb-<workspace-id>.<random>.azuredatabricks.net for
Azure, <workspace-id>.cloud.databricks.com for AWS).
security:
- bearerAuth: []
tags:
- name: Clusters
description: >-
Manage Databricks clusters for running data engineering and data science
workloads on Apache Spark.
- name: Jobs
description: >-
Create and manage automated workloads including notebooks, JARs, Python
scripts, and multi-task workflows.
- name: Workspace
description: >-
Manage workspace objects such as notebooks, folders, and libraries.
paths:
/2.0/clusters/create:
post:
operationId: createCluster
summary: Databricks Create a New Cluster
description: >-
Creates a new Spark cluster. This method acquires new instances from the
cloud provider and starts the Spark driver and worker processes. The
cluster is created asynchronously; use the cluster_id returned to poll
for status.
tags:
- Clusters
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateClusterRequest'
examples:
CreateclusterRequestExample:
summary: Default createCluster request
x-microcks-default: true
value:
cluster_name: example_value
spark_version: example_value
node_type_id: '500123'
driver_node_type_id: '500123'
num_workers: 10
autoscale:
min_workers: 10
max_workers: 10
spark_conf: example_value
aws_attributes:
first_on_demand: 10
availability: SPOT
zone_id: '500123'
instance_profile_arn: example_value
spot_bid_price_percent: 10
ebs_volume_type: GENERAL_PURPOSE_SSD
ebs_volume_count: 10
ebs_volume_size: 10
azure_attributes:
first_on_demand: 10
availability: SPOT_AZURE
spot_bid_max_price: 42.5
gcp_attributes:
use_preemptible_executors: true
google_service_account: example_value
availability: GCP_PREEMPTIBLE
custom_tags: example_value
spark_env_vars: example_value
autotermination_minutes: 10
enable_elastic_disk: true
instance_pool_id: '500123'
policy_id: '500123'
enable_local_disk_encryption: true
runtime_engine: STANDARD
data_security_mode: NONE
single_user_name: example_value
init_scripts:
- workspace: {}
volumes: {}
dbfs: {}
ssh_public_keys:
- example_value
responses:
'200':
description: Cluster creation initiated successfully.
content:
application/json:
schema:
type: object
properties:
cluster_id:
type: string
description: The unique identifier of the newly created cluster.
examples:
- '1234-567890-abcde123'
examples:
Createcluster200Example:
summary: Default createCluster 200 response
x-microcks-default: true
value:
cluster_id: '500123'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2.0/clusters/list:
get:
operationId: listClusters
summary: Databricks List All Clusters
description: >-
Returns information about all clusters in the workspace, including
terminated clusters. Clusters are ordered by cluster_id.
tags:
- Clusters
parameters:
- name: can_use_client
in: query
required: false
description: Filter clusters by client compatibility.
schema:
type: string
example: example_value
responses:
'200':
description: Successfully retrieved the list of clusters.
content:
application/json:
schema:
type: object
properties:
clusters:
type: array
items:
$ref: '#/components/schemas/ClusterDetails'
examples:
Listclusters200Example:
summary: Default listClusters 200 response
x-microcks-default: true
value:
clusters:
- cluster_id: '500123'
cluster_name: example_value
spark_version: example_value
node_type_id: '500123'
driver_node_type_id: '500123'
num_workers: 10
state: PENDING
state_message: example_value
start_time: 10
terminated_time: 10
last_state_loss_time: 10
last_activity_time: 10
last_restarted_time: 10
creator_user_name: example_value
cluster_source: UI
spark_conf: example_value
custom_tags: example_value
spark_env_vars: example_value
autotermination_minutes: 10
enable_elastic_disk: true
instance_pool_id: '500123'
policy_id: '500123'
data_security_mode: example_value
single_user_name: example_value
runtime_engine: example_value
default_tags: example_value
cluster_log_status:
last_attempted: 10
last_exception: example_value
termination_reason:
code: example_value
type: example_value
parameters: example_value
disk_spec:
disk_count: 10
disk_size: 10
disk_type: {}
executors:
- {}
jdbc_port: 10
spark_context_id: '500123'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2.0/clusters/get:
get:
operationId: getCluster
summary: Databricks Get Cluster Details
description: >-
Retrieves detailed information about a cluster, including its current
state, configuration, and runtime properties.
tags:
- Clusters
parameters:
- name: cluster_id
in: query
required: true
description: The unique identifier of the cluster.
schema:
type: string
example: '500123'
responses:
'200':
description: Successfully retrieved cluster details.
content:
application/json:
schema:
$ref: '#/components/schemas/ClusterDetails'
examples:
Getcluster200Example:
summary: Default getCluster 200 response
x-microcks-default: true
value:
cluster_id: '500123'
cluster_name: example_value
spark_version: example_value
node_type_id: '500123'
driver_node_type_id: '500123'
num_workers: 10
autoscale:
min_workers: 10
max_workers: 10
state: PENDING
state_message: example_value
start_time: 10
terminated_time: 10
last_state_loss_time: 10
last_activity_time: 10
last_restarted_time: 10
creator_user_name: example_value
cluster_source: UI
spark_conf: example_value
custom_tags: example_value
spark_env_vars: example_value
autotermination_minutes: 10
enable_elastic_disk: true
instance_pool_id: '500123'
policy_id: '500123'
data_security_mode: example_value
single_user_name: example_value
runtime_engine: example_value
default_tags: example_value
cluster_log_status:
last_attempted: 10
last_exception: example_value
termination_reason:
code: example_value
type: example_value
parameters: example_value
disk_spec:
disk_count: 10
disk_size: 10
disk_type:
azure_disk_volume_type: example_value
ebs_volume_type: example_value
driver:
private_ip: example_value
public_dns: example_value
node_id: '500123'
instance_id: '500123'
start_timestamp: 10
host_private_ip: example_value
executors:
- private_ip: example_value
public_dns: example_value
node_id: '500123'
instance_id: '500123'
start_timestamp: 10
host_private_ip: example_value
jdbc_port: 10
spark_context_id: '500123'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2.0/clusters/start:
post:
operationId: startCluster
summary: Databricks Start a Terminated Cluster
description: >-
Starts a terminated cluster given its cluster_id. This is similar to
creating a cluster except it uses the configuration of the previously
terminated cluster.
tags:
- Clusters
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- cluster_id
properties:
cluster_id:
type: string
description: The cluster to start.
examples:
StartclusterRequestExample:
summary: Default startCluster request
x-microcks-default: true
value:
cluster_id: '500123'
responses:
'200':
description: Cluster start initiated successfully.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2.0/clusters/restart:
post:
operationId: restartCluster
summary: Databricks Restart a Cluster
description: >-
Restarts a Spark cluster given its cluster_id. If the cluster is not in
a RUNNING state, nothing happens.
tags:
- Clusters
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- cluster_id
properties:
cluster_id:
type: string
description: The cluster to restart.
examples:
RestartclusterRequestExample:
summary: Default restartCluster request
x-microcks-default: true
value:
cluster_id: '500123'
responses:
'200':
description: Cluster restart initiated successfully.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2.0/clusters/delete:
post:
operationId: terminateCluster
summary: Databricks Terminate a Cluster
description: >-
Terminates a Spark cluster given its cluster_id. The cluster is removed
after being terminated. Use the permanent-delete endpoint if you want to
remove the cluster configuration entirely.
tags:
- Clusters
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- cluster_id
properties:
cluster_id:
type: string
description: The cluster to terminate.
examples:
TerminateclusterRequestExample:
summary: Default terminateCluster request
x-microcks-default: true
value:
cluster_id: '500123'
responses:
'200':
description: Cluster termination initiated successfully.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2.0/clusters/permanent-delete:
post:
operationId: permanentDeleteCluster
summary: Databricks Permanently Delete a Cluster
description: >-
Permanently deletes a Spark cluster. If the cluster is running, it is
terminated and resources are asynchronously removed. If the cluster is
terminated, it is immediately removed. A cluster can only be permanently
deleted by an admin or the cluster creator.
tags:
- Clusters
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- cluster_id
properties:
cluster_id:
type: string
description: The cluster to permanently delete.
examples:
PermanentdeleteclusterRequestExample:
summary: Default permanentDeleteCluster request
x-microcks-default: true
value:
cluster_id: '500123'
responses:
'200':
description: Cluster permanently deleted.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2.0/clusters/edit:
post:
operationId: editCluster
summary: Databricks Edit Cluster Configuration
description: >-
Edits the configuration of a cluster to match the provided attributes.
The cluster must be in a RUNNING or TERMINATED state. If the cluster is
running, it will be restarted to apply the changes.
tags:
- Clusters
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EditClusterRequest'
examples:
EditclusterRequestExample:
summary: Default editCluster request
x-microcks-default: true
value:
cluster_id: '500123'
cluster_name: example_value
spark_version: example_value
node_type_id: '500123'
driver_node_type_id: '500123'
num_workers: 10
autoscale:
min_workers: 10
max_workers: 10
spark_conf: example_value
custom_tags: example_value
spark_env_vars: example_value
autotermination_minutes: 10
enable_elastic_disk: true
instance_pool_id: '500123'
policy_id: '500123'
data_security_mode: NONE
single_user_name: example_value
runtime_engine: STANDARD
responses:
'200':
description: Cluster configuration updated successfully.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2.0/clusters/events:
post:
operationId: listClusterEvents
summary: Databricks List Cluster Events
description: >-
Retrieves a list of events about the activity of a cluster. Events are
returned in reverse chronological order. This endpoint can be used to
audit cluster activity and monitor lifecycle changes.
tags:
- Clusters
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- cluster_id
properties:
cluster_id:
type: string
description: The ID of the cluster to retrieve events for.
start_time:
type: integer
format: int64
description: Start timestamp in milliseconds for the event query range.
end_time:
type: integer
format: int64
description: End timestamp in milliseconds for the event query range.
order:
type: string
enum:
- DESC
- ASC
description: Sort order for results.
event_types:
type: array
items:
type: string
enum:
- CREATING
- DID_NOT_EXPAND_DISK
- EXPANDED_DISK
- FAILED_TO_EXPAND_DISK
- INIT_SCRIPTS_STARTING
- INIT_SCRIPTS_FINISHED
- STARTING
- RESTARTING
- TERMINATING
- EDITED
- RUNNING
- RESIZING
- UPSIZE_COMPLETED
- NODES_LOST
- DRIVER_HEALTHY
- DRIVER_NOT_RESPONDING
- DRIVER_UNAVAILABLE
- SPARK_EXCEPTION
- PINNED
- UNPINNED
description: Filter by specific event types.
offset:
type: integer
format: int64
description: Offset for pagination.
limit:
type: integer
format: int64
description: Maximum number of events to return (max 500).
examples:
ListclustereventsRequestExample:
summary: Default listClusterEvents request
x-microcks-default: true
value:
cluster_id: '500123'
start_time: 10
end_time: 10
order: DESC
event_types:
- CREATING
offset: 10
limit: 10
responses:
'200':
description: Successfully retrieved cluster events.
content:
application/json:
schema:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/ClusterEvent'
next_page:
type: object
properties:
cluster_id:
type: string
end_time:
type: integer
format: int64
offset:
type: integer
format: int64
total_count:
type: integer
format: int64
examples:
Listclusterevents200Example:
summary: Default listClusterEvents 200 response
x-microcks-default: true
value:
events:
- cluster_id: '500123'
timestamp: 10
type: example_value
details:
current_num_workers: 10
target_num_workers: 10
previous_attributes: example_value
attributes: example_value
previous_cluster_size: example_value
cluster_size: example_value
cause: example_value
reason: {}
next_page:
cluster_id: '500123'
end_time: 10
offset: 10
total_count: 10
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2.1/jobs/create:
post:
operationId: createJob
summary: Databricks Create a New Job
description: >-
Creates a new job with the provided settings. The job can be configured
with a single task or multiple tasks with dependencies forming a
directed acyclic graph (DAG).
tags:
- Jobs
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateJobRequest'
examples:
CreatejobRequestExample:
summary: Default createJob request
x-microcks-default: true
value:
name: Example Title
tasks:
- task_key: example_value
description: A sample description.
depends_on: {}
existing_cluster_id: '500123'
job_cluster_key: example_value
notebook_task: {}
spark_jar_task: {}
spark_python_task: {}
spark_submit_task: {}
pipeline_task: {}
python_wheel_task: {}
sql_task: {}
dbt_task: {}
run_if: ALL_SUCCESS
timeout_seconds: 10
max_retries: 10
min_retry_interval_millis: 10
retry_on_timeout: true
libraries: {}
job_clusters:
- job_cluster_key: example_value
email_notifications:
on_start:
- {}
on_success:
- {}
on_failure:
- {}
on_duration_warning_threshold_exceeded:
- {}
no_alert_for_skipped_runs: true
webhook_notifications:
on_start:
- {}
on_success:
- {}
on_failure:
- {}
on_duration_warning_threshold_exceeded:
- {}
notification_settings:
no_alert_for_skipped_runs: true
no_alert_for_canceled_runs: true
timeout_seconds: 10
schedule:
quartz_cron_expression: example_value
timezone_id: '500123'
pause_status: PAUSED
continuous:
pause_status: PAUSED
trigger:
pause_status: PAUSED
file_arrival:
url: https://www.example.com
min_time_between_triggers_seconds: 10
wait_after_last_change_seconds: 10
max_concurrent_runs: 10
git_source:
git_url: https://www.example.com
git_provider: gitHub
git_branch: example_value
git_tag: example_value
git_commit: example_value
tags: example_value
format: SINGLE_TASK
queue:
enabled: true
parameters:
- name: Example Title
default: example_value
run_as:
user_name: example_value
service_principal_name: example_value
access_control_list:
- user_name: example_value
group_name: example_value
service_principal_name: example_value
permission_level: CAN_MANAGE
responses:
'200':
description: Job created successfully.
content:
application/json:
schema:
type: object
properties:
job_id:
type: integer
format: int64
description: The canonical identifier for the newly created job.
examples:
- 11223344
examples:
Createjob200Example:
summary: Default createJob 200 response
x-microcks-default: true
value:
job_id: '500123'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2.1/jobs/list:
get:
operationId: listJobs
summary: Databricks List All Jobs
description: >-
Retrieves a list of jobs in the workspace. Results are paginated and can
be filtered by name.
tags:
- Jobs
parameters:
- name: limit
in: query
required: false
description: >-
The number of jobs to return. This value must be greater than 0 and
less than or equal to 25. The default value is 20.
schema:
type: integer
default: 20
maximum: 25
example: 10
- name: offset
in: query
required: false
description: The offset of the first job to return.
schema:
type: integer
default: 0
example: 10
- name: name
in: query
required: false
description: >-
A filter on the list based on the exact (case-insensitive) job name.
schema:
type: string
example: Example Title
- name: expand_tasks
in: query
required: false
description: Whether to include task and cluster details in the response.
schema:
type: boolean
default: false
example: true
responses:
'200':
description: Successfully retrieved the list of jobs.
content:
application/json:
schema:
type: object
properties:
jobs:
type: array
items:
$ref: '#/components/schemas/Job'
has_more:
type: boolean
description: Whether there are more jobs to list.
examples:
Listjobs200Example:
summary: Default listJobs 200 response
x-microcks-default: true
value:
jobs:
- job_id: '500123'
creator_user_name: example_value
run_as_user_name: example_value
created_time: 10
has_more: true
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/2.1/jobs/get:
get:
operationId: getJob
summary: Databricks Get a Job
description: >-
Retrieves the details of a single job, including its settings, creator,
and run history summary.
tags:
- Jobs
parameters:
- name: job_id
in: query
required: true
description: The canonical identifier of the job to retrieve.
schema:
type: integer
format: int64
example: '500123'
responses:
'200':
description: Successfully retrieved the job.
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
examples:
Getjob200Example:
summary: Default getJob 200 response
x-microcks-default: true
value:
job_id: '500123'
creator_user_name: example_value
run_as_user_name: example_value
settings:
name: Example Title
tasks:
# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/databricks/refs/heads/main/openapi/databricks-openapi.yml