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 |
---|---|
|
|
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 |
|
The absolute path of the notebook or directory. This field is required. |
recursive |
|
The flag that specifies whether to delete the object recursively. It is |
Export
Endpoint |
HTTP Method |
---|---|
|
|
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 |
|
The absolute path of the notebook or directory. Exporting a directory is supported only for |
format |
This specifies the format of the exported file. By default, this is |
|
direct_download |
|
Flag to enable direct download. If it is |
Get status
Endpoint |
HTTP Method |
---|---|
|
|
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 |
|
The absolute path of the notebook or directory. This field is required. |
Import
Endpoint |
HTTP Method |
---|---|
|
|
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 |
|
The absolute path of the notebook or directory. Importing directory is only support for |
format |
This specifies the format of the file to be imported. By default, this is |
|
language |
The language. If format is set to |
|
content |
|
The base64-encoded content. This has a limit of 10 MB.
If the limit (10MB) is exceeded, exception with error code |
overwrite |
|
The flag that specifies whether to overwrite existing object. It is |
List
Endpoint |
HTTP Method |
---|---|
|
|
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 |
|
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 |
---|---|
|
|
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.
Data structures
In this section:
ObjectInfo
The information of the object in workspace. It is returned by list
and get-status
.
Field Name |
Type |
Description |
---|---|---|
object_type |
The type of the object. |
|
object_id |
|
Unique identifier for the object. |
path |
|
The absolute path of the object. |
language |
The language of the object. This value is set only if the object type is |
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 |