Source Code Bundles
A file contains a sequence of bytes. Any file on your computer can be uploaded to B2 and stored in a Cloud Storage, as long as it's not too big. Files can range in size from 0 bytes to 5 billion bytes.
Once a file is uploaded, you can download it right away, or wait years and then download it. You can download it once, or give the URL to all of your friends and they can all download it.
Uploading the same file name more than once results in multiple versions of the same file. This can be useful for tracking the history of a document. See File Versions for more details.
The API calls related to files are:
Files have names, which are set when a file is uploaded. Once a file is uploaded, its name cannot be changed. You can then download a file if you know its name.
Names can be pretty much any UTF-8 string up to 1024 bytes long. There are a few picky rules:
These are all valid file names:
To help ensure that B2 files can be easily exported to disk file systems, there is a maximum of 250 bytes of UTF-8 in each segment of a file name. A segment is the part between slashes. So while file names can be up to 1024 bytes long, a file name that long must have at least four slashes in it, with each of the parts between the slashes being 250 bytes or less.
In addition to a name, each file uploaded has a unique ID that identifies that specific version of that file. A File ID will not be more than 200 characters. If you want to download an older version of a file, you'll need to know its File ID. File IDs look like this:
If you have uploaded a file called
The first part of the URL comes is the download URL that you get from
Folders (There Are No Folders)
A bucket holds files. There is no hierarchy of folders, just one long, flat list of file names. For example, a bucket might have four files in it, with these four names:
cats/cat.jpg cats/kitten.jpg dogs/dog.jpg dogs/puppy.jpg
There are no folders. The name of the first file is
Even though there are no folders, many of the tools that work with files
in a bucket act like there are folders. The file browser on the Backblaze
web site acts like there are folders, and so does the
$ b2 ls my_bucket cats/ dogs/ $ b2 ls my_bucket cats cat.jpg kitten.jpg
We recommend that you use "/" to separate folder names, just like you would for files on your computer. (Or just like you would use "\" if you use Windows.) That way the tools can figure out the implied folder structure.
To ensure the integrity of your data, when you upload a file you must provide a SHA1 checksum of the data. This ensures that if any of the data is corrupted in the network on its way to B2, it will be detected before the file is stored. When you download a file, the SHA1 checksum is attached so that you can verify that the data you receive is intact.
When you upload a file, you also provide a MIME type for the file, which
will be used when a browser downloads the file so that it knows what
kind of file it is. For example, if you say that your file
Each file has information associated with it, in addition to the sequence of bytes that the file contains. Every file has a size (the number of bytes in the file), a MIME type, and a SHA1 checksum. You can also add your own custom information.
Your custom file information can be up to 10 key/value pairs. Each key is a UTF-8 string up to 50 bytes long, and can contain letters, numbers, "-" and "_". Each key is converted to lowercase. Names that begin with "b2-" are reserved. There is an overall 7000-byte limit on the headers needed for file name and file info. (See next section.)
For names that don't start with "b2-", there is no limit on the size or content of the values, other than the overall size limit.
Names that start with "b2-" must be in the list of defined "b2-" names and their values must be valid. See the list below for details. B2 rejects any upload request with an unexpected "b2-" file info name. B2 also rejects any upload with a "b2-" file info name whose value doesn't meet the specified format for that name.
If this is present, B2 will use it as the value of the 'Content-Disposition' header when the file is downloaded (unless it's overridden by a value given in the download request). The value must match the grammar specified in RFC 6266. Parameter continuations are not supported. 'Extended-value's are supported for charset 'UTF-8' (case-insensitive) when the language is empty. Note that this file info will not be included in downloads as a x-bz-info-b2-content-disposition header. Instead, it (or the value specified in a request) will be in the Content-Disposition.
You provide the File Info with the
Recommended File Info key/value: If the original source of the file being uploaded has a last modified
time concept, Backblaze recommends using
Recommended File Info key/value: If this is a large file (meaning the caller is using b2_start_large_file)
and if the caller knows the SHA1 of the entire large file being uploaded,
Backblaze recommends using
HTTP Header Size Limit
The file name and file info must fit, along with the other necessary headers, within an 8KB limit imposed by some web servers and proxies. To ensure this, both now and in the future, B2 limits the combined header size for the file name and all file info to 7000 bytes. This limit applies to the fully encoded HTTP header line, including the carriage-return and newline. This header line is counted as 40 bytes: