Workspace API 2.0

The Workspace API allows you to list, import, export, and delete notebooks and folders. The maximum allowed size of a request to the Workspace API is 10MB. See Cluster log delivery examples for a how to guide on this API.

Important

To access Databricks REST APIs, you must authenticate.

Delete

Endpoint

HTTP Method

2.0/workspace/delete

POST

Delete 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

Request:

curl --netrc --request POST \
  https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/workspace/delete \
  --header 'Accept: application/json' \
  --data '{ "path": "/Users/me@example.com/MyFolder", "recursive": true }'

If successful, this endpoint returns no response.

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

Export a notebook or contents of an entire directory. You can also export a Databricks Repo, or a notebook or directory from a Databricks Repo. If path does not exist, this call returns an error RESOURCE_DOES_NOT_EXIST. You can export a directory only in DBC format. If the exported data exceeds the size limit, this call returns an error MAX_NOTEBOOK_SIZE_EXCEEDED or BAD_REQUEST. This API does not support exporting a library.

Examples

Export a notebook

Request:

curl --netrc --request GET \
  https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/workspace/export \
  --header 'Accept: application/json' \
  --data '{ "path": "/Users/me@example.com/MyFolder/MyNotebook", "format": "SOURCE", "direct_download": true }'
curl --netrc --request GET \
  https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/workspace/export \
  --header 'Accept: application/json' \
  --data '{ "path": "/Repos/me@example.com/MyFolder/MyNotebook", "format": "SOURCE", "direct_download": true }'

Response:

If the direct_download field was set to false or was omitted from the request, a base64-encoded version of the content is returned, for example:

{
  "content": "Ly8gRGF0YWJyaWNrcyBub3RlYm9vayBzb3VyY2UKMSsx",
}

Otherwise, if direct_download was set to true in the request, the content is downloaded.

Export a workspace file

This functionality is in Public Preview.

Request:

curl --netrc --request GET \
  https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/workspace/export \
  --header 'Accept: application/json' \
  --data '{ "path": "/Users/me@example.com/MyRepo/my_file.txt", "format": "AUTO", “direct_download”: true }'

Response:

If the direct_download field was set to false or was omitted from the request, a base64-encoded version of the content is returned, for example:

{
  "content": "Ly8gRGF0YWJyaWNrcyBub3RlYm9vayBzb3VyY2UKMSsx",
}

Otherwise, if direct_download was set to true in the request, the content is downloaded.

Request structure

Field Name

Type

Description

path

STRING

The absolute path of the notebook or directory. Exporting a directory is supported only for DBC. This field is required.

format

ExportFormat

This specifies the format of the exported file. By default, this is SOURCE. 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 is 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

Request:

curl --netrc --request GET \
  https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/workspace/get-status \
  --header 'Accept: application/json' \
  --data '{ "path": "/Users/me@example.com/MyFolder/MyNotebook" }'

Response:

{
  "object_type": "NOTEBOOK",
  "path": "/Users/me@example.com/MyFolder/MyNotebook",
  "language": "PYTHON",
  "object_id": 123456789012345
}

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.

object_id

INT64

Unique identifier for the object.

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

Import a notebook, workspace file, 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. You can use only DBC format to import a directory.

Example

Import a base64-encoded string:

curl --netrc --request POST \
  https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/workspace/import \
  --header 'Accept: application/json' \
  --data '{ "path": "/Users/me@example.com/MyFolder/MyNotebook", "content": "Ly8gRGF0YWJyaWNrcyBub3RlYm9vayBzb3VyY2UKMSsx", "language": "PYTHON", "overwrite": true, "format": "SOURCE" }'

Import a local notebook:

curl --netrc --request POST \
  https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/workspace/import \
  --header 'Content-Type: multipart/form-data' \
  --form path=/Users/me@example.com/MyFolder/MyNotebook \
  --form content=@myCode.py.zip

Import a local file (Public Preview):

curl --netrc --request POST \
  https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/workspace/import \
  --header 'Content-Type: multipart/form-data' \
  --form path=/Repos/me@example.com/MyRepo/my_file.py \
  --form format=AUTO \
  --form content=@non-notebook.py

If successful, this endpoint returns no response.

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. 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 is 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

List 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

List directories and their contents:

Request:

curl --netrc --request GET \
  https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/workspace/list \
  --header 'Accept: application/json' \
  --data '{ "path": "/Users/me@example.com" }'

Response:

{
  "objects": [
    {
      "path": "/Users/me@example.com/MyFolder",
      "object_type": "DIRECTORY",
      "object_id": 234567890123456
    },
    {
      "path": "/Users/me@example.com/MyFolder/MyNotebook",
      "object_type": "NOTEBOOK",
      "language": "PYTHON",
      "object_id": 123456789012345
    },
    {
      "..."
    }
  ]
}

List repos:

curl --netrc --request GET \
  https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/workspace/list \
  --header 'Accept: application/json' \
  --data '{ "path": "/Repos/me@example.com" }'

Response:

{
  "objects": [
    {
      "path": "/Repos/me@example.com/MyRepo1",
      "object_type": "REPO",
      "object_id": 234567890123456
    },
    {
      "path": "/Repos/me@example.com/MyRepo2",
      "object_type": "REPO",
      "object_id": 123456789012345
    },
    {
      "..."
    }
  ]
}

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

Create 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. If this operation fails it may have succeeded in creating some of the necessary parent directories.

Example

Request:

curl --netrc --request POST \
  https://dbc-a1b2345c-d6e7.cloud.databricks.com/api/2.0/workspace/mkdirs \
  --header 'Accept: application/json' \
  --data '{ "path": "/Users/me@example.com/MyFolder" }'

If successful, this endpoint returns no response.

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 is returned by list and get-status.

Field Name

Type

Description

object_type

ObjectType

The type of the object.

object_id

INT64

Unique identifier for the object.

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.

Format

Description

AUTO

(Public Preview) The item is imported/exported as either a workspace file or a notebook, depending on an analysis of the item’s extension and the header content provided in the request. See also Import a file and convert it to a notebook.

If the item is imported as a notebook, then the item’s extension is automatically removed.

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.

Language

Description

SCALA

Scala notebook.

PYTHON

Python notebook.

SQL

SQL notebook.

R

R notebook.

ObjectType

The type of the object in workspace.

Type

Description

NOTEBOOK

Notebook

DIRECTORY

Directory

FILE

File

LIBRARY

Library

REPO

Repository