Workspace API

The Workspace API allows you to list/import/export/delete notebooks/folders via the API. See Workspace for more information. See Workspace API Examples for a how to guide on this API. For an easy to use command line client of the workspace API, please reference Databricks CLI.


Delete

Endpoint HTTP Method
2.0/workspace/delete POST

Deletes an object or a directory (and optionally recursively deletes all objects in the directory). If path does not exist, this call returns an error RESOURCE_DOES_NOT_EXIST. If path is a non-empty directory and recursive is set to false, this call returns an error DIRECTORY_NOT_EMPTY. Object deletion cannot be undone and deleting a directory recursively is not atomic. Example of request:

{
  "path": "/Users/user@example.com/project",
  "recursive": true
}

Request Structure

Field Name Type Description
path STRING The absolute path of the notebook or directory. This field is required.
recursive BOOL The flag that specifies whether to delete the object recursively. It is false by default. Please note this deleting directory is not atomic. If it fails in the middle, some of objects under this directory may be deleted and cannot be undone.

Export

Endpoint HTTP Method
2.0/workspace/export GET

Exports a notebook or contents of an entire directory. If path does not exist, this call returns an error RESOURCE_DOES_NOT_EXIST. One can only export a directory in DBC format. If the exported data would exceed size limit, this call returns an error MAX_NOTEBOOK_SIZE_EXCEEDED. Currently, this API does not support exporting a library. Example of request:

{
  "path": "/Users/user@example.com/project/ScalaExampleNotebook",
  "format": "SOURCE"
}

Example of response, where content is base64-encoded:

{
  "content": "Ly8gRGF0YWJyaWNrcyBub3RlYm9vayBzb3VyY2UKMSsx",
}

Alternaitvely, one can download the exported file by enabling direct_download:

curl -n -o example.scala \
  'https://XX.cloud.databricks.com/api/2.0/workspace/export?path=/Users/user@example.com/ScalaExampleNotebook&direct_download=true'

Request Structure

Field Name Type Description
path STRING The absolute path of the notebook or directory. Exporting directory is only support for DBC format. This field is required.
format ExportFormat This specifies the format of the exported file. By default, this is SOURCE. However it may be one of: SOURCE, HTML, JUPYTER, DBC. The value is case sensitive.
direct_download BOOL Flag to enable direct download. If it is true, the response will be the exported file itself. Otherwise, the response contains content as base64 encoded string. See Export a notebook or folder for more information about how to use it.

Response Structure

Field Name Type Description
content BYTES The base64-encoded content. If the limit (10MB) is exceeded, exception with error code MAX_NOTEBOOK_SIZE_EXCEEDED will be thrown.

Get Status

Endpoint HTTP Method
2.0/workspace/get-status GET

Gets the status of an object or a directory. If path does not exist, this call returns an error RESOURCE_DOES_NOT_EXIST. Example of request:

{
  "path": "/Users/user@example.com/project/ScaleExampleNotebook"
}

Example of response:

{
  "path": "/Users/user@example.com/project/ScalaExampleNotebook",
  "language": "SCALA",
  "object_type": "NOTEBOOK"
}

Request Structure

Field Name Type Description
path STRING The absolute path of the notebook or directory. This field is required.

Response Structure

Field Name Type Description
object_type ObjectType The type of the object. It could be NOTEBOOK, DIRECTORY or LIBRARY.
path STRING The absolute path of the object.
language Language The language of the object. This value is set only if the object type is NOTEBOOK.

Import

Endpoint HTTP Method
2.0/workspace/import POST

Imports a notebook or the contents of an entire directory. If path already exists and overwrite is set to false, this call returns an error RESOURCE_ALREADY_EXISTS. One can only use DBC format to import a directory. Example of request, where content is the base64-encoded string of 1+1:

{
  "content": "MSsx\n",
  "path": "/Users/user@example.com/project/ScalaExampleNotebook",
  "language": "SCALA",
  "overwrite": true,
  "format": "SOURCE"
}

Alternatively, one can import a local file directly:

In the following example, replace YOUR_DOMAIN with the <ACCOUNT>.cloud.databricks.com domain name of your Databricks deployment.

curl -n -F path=/Users/user@example.com/project/ScalaExampleNotebook -F language=SCALA \
  -F content=@example.scala \
  https://YOUR_DOMAIN/api/2.0/workspace/import

Request Structure

Field Name Type Description
path STRING The absolute path of the notebook or directory. Importing directory is only support for DBC format. This field is required.
format ExportFormat This specifies the format of the file to be imported. By default, this is SOURCE. However it may be one of: SOURCE, HTML, JUPYTER, DBC. The value is case sensitive.
language Language The language. If format is set to SOURCE, this field is required; otherwise, it will be ignored.
content BYTES The base64-encoded content. This has a limit of 10 MB. If the limit (10MB) is exceeded, exception with error code MAX_NOTEBOOK_SIZE_EXCEEDED will be thrown. This parameter might be absent, and instead a posted file will be used. See Import a notebook or directory for more information about how to use it.
overwrite BOOL The flag that specifies whether to overwrite existing object. It is false by default. For DBC format, overwrite is not supported since it may contain a directory.

List

Endpoint HTTP Method
2.0/workspace/list GET

Lists the contents of a directory, or the object if it is not a directory. If the input path does not exist, this call returns an error RESOURCE_DOES_NOT_EXIST. Example of request:

{
  "path": "/Users/user@example.com/"
}

Example of response:

{
  "objects": [
    {
      "path": "/Users/user@example.com/project",
      "object_type": "DIRECTORY"
    },
    {
      "path": "/Users/user@example.com/PythonExampleNotebook",
      "language": "PYTHON",
      "object_type": "NOTEBOOK"
    }
  ]
}

Request Structure

Field Name Type Description
path STRING The absolute path of the notebook or directory. This field is required.

Response Structure

Field Name Type Description
objects An array of ObjectInfo List of objects.

Mkdirs

Endpoint HTTP Method
2.0/workspace/mkdirs POST

Creates the given directory and necessary parent directories if they do not exists. If there exists an object (not a directory) at any prefix of the input path, this call returns an error RESOURCE_ALREADY_EXISTS. Note that if this operation fails it may have succeeded in creating some of the necessary parrent directories. Example of request:

{
  "path": "/Users/user@example.com/project"
}

Request Structure

Field Name Type Description
path STRING The absolute path of the directory. If the parent directories do not exist, it will also create them. If the directory already exists, this command will do nothing and succeed. This field is required.

Data Structures

ObjectInfo

The information of the object in workspace. It will be returned by list and get-status.

Field Name Type Description
object_type ObjectType The type of the object. It could be NOTEBOOK, DIRECTORY or LIBRARY.
path STRING The absolute path of the object.
language Language The language of the object. This value is set only if the object type is NOTEBOOK.

ExportFormat

The format for notebook import and export.

SOURCE The notebook will be imported/exported as source code.
HTML The notebook will be imported/exported as an HTML file.
JUPYTER The notebook will be imported/exported as a Jupyter/IPython Notebook file.
DBC The notebook will be imported/exported as Databricks archive format.

Language

The language of notebook.

SCALA Scala notebook.
PYTHON Python notebook.
SQL SQL notebook.
R R notebook.

ObjectType

The type of the object in workspace.

NOTEBOOK Notebook
DIRECTORY Directory
LIBRARY Library