Files API versions

The Files API has two versions, 2.0 and 3.0. For Files API 2.0, see the Files API 2.0 reference. For Files API 3.0, see the Files API 3.0 reference.

Hostname and endpoint prefix

The two versions send requests to different hostnames with different endpoint prefixes:

Version	Hostname	Endpoint prefix
Files API 2.0	Your workspace hostname	/api/2.0/fs
Files API 3.0	Your workspace's regional hostname	/api/3.0/fs

Version	Hostname	Endpoint prefix
Files API 2.0	Your workspace hostname	/api/2.0/fs
Files API 3.0	Your workspace's regional hostname	/api/3.0/fs

To build the regional hostname for your workspace, see Use the Files API with the regional hostname.

Network requirements

Files API 3.0 has additional network requirements, both from your network to Databricks and from Databricks to your storage. See Network connectivity for the Files API.

New features in 3.0

Files API 3.0 adds the following features:

• Multipart upload: upload a file larger than 5000 MiB, or a file whose size is unknown when the upload starts, in parts. See Upload large files with multipart upload.
• Conditional requests: Files API 2.0 supports If-Unmodified-Since on downloads only. Files API 3.0 adds If-Match, If-None-Match, and If-Modified-Since, and lets writes and deletes depend on a file's ETag. See Use conditional requests.

Behavior changes in 3.0

If you move code from Files API 2.0 to 3.0, note the following changes:

• Uploads require the Content-Length request header. If you don't know the total file size in advance, use multipart upload.
• DELETE is idempotent. Deleting a file that does not exist returns 204 No Content. To get a 404 for a file that does not exist, as in Files API 2.0, send If-Match: *. See Conditional deletes.
• A successful upload (PUT) returns 200 OK instead of 204 No Content.