b2_delete_file_version
- 11 Sep 2026
- Print
- DarkLight
b2_delete_file_version
- Updated on 11 Sep 2026
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Post
/b2api/v4/b2_delete_file_version
Deletes one version of a file
If the version you delete is the latest version, and there are older versions, then the most recent older version will become the current version, and be the one that you'll get when downloading by name. See File Versions for more details.
When used on an unfinished large file, this call has the same effect as b2_cancel_large_file.
NOTE:
This API endpoint can be called using a GET request by converting the parameters in the request body to query parameters.
NOTE:
Managing Versioned Objects
While versioning provides valuable protection against accidental deletions and overwrites, uploading millions of versions of the same object into a bucket may significantly degrade performance of object deletion and listing operations, increase the rate of HTTP 503 (Service Unavailable) responses, and will eventually result in your account being blocked from further uploads.
To avoid this, configure lifecycle rules to automatically expire old versions after a specified number of days or limit the number of retained versions per object. If you suspect your account has been affected, contact Backblaze support for assistance.
API Versions
v1: Application keys (July 26, 2018)
Incompatible change: After calling b2_authorize_account with an application key that does not have the right permissions, this call will return a 401 Unauthorized.
v1: Original release (September 22, 2015)
For information on all API versions, view our API changelog.
Header parameters
Authorization
stringRequired
An account authorization token, obtained from b2_authorize_account.
The token must have the deleteFiles capability.
Body parameters
object
fileName
string Required
The name of the file.
ExampleFILE_NAME
fileId
string Required
The ID of the file, as returned by b2_upload_file, b2_list_file_names, or b2_list_file_versions.
ExampleFILE_ID
bypassGovernance
boolean
Must be specified and set to true if deleting a file version protected by Object Lock governance mode retention settings. Setting the value requires the bypassGovernance application key capability. See Object Lock for more information.
Exampletrue
Responses
200
The request succeeded.
object
fileId
string
The unique ID of the file version that was deleted.
Example4_h4a48fe8875c6214145260818_f000000000000472a_d20140104_m032022_c001_v0000123_t0104
fileName
string
The name of the file.
Exampletyping_test.txt
400
| status | code | description |
|---|---|---|
| 400 | bad_bucket_id | The requested bucket ID does not match an existing bucket. |
| 400 | bad_request | The request had the wrong fields or illegal values. The message returned with the error will describe the problem. | 400 | file_not_present | File not present: <fileName> <fileId>. |
object
status
integer
The numeric HTTP status code. Always matches the status in the HTTP response.
Example400
code
string
A single-identifier code that identifies the error.
Exampleinvalid_bucket_name
message
string
A human-readable message, in English, saying what went wrong.
Examplebucket name is too long
401
| status | code | description |
|---|---|---|
| 401 | bad_auth_token | The auth token used is not valid. Call b2_authorize_account again to either get a new one, or an error message describing the problem. |
| 401 | expired_auth_token | The auth token used has expired. Call b2_authorize_account again to get a new one. |
| 401 | unauthorized | The auth token used is valid, but does not authorize this call with these parameters. The capabilities of an auth token are determined by the application key used with b2_authorize_account. |
| 401 | access_denied | Access Denied. The delete was not allowed because Object Lock is enabled on the file. |
Was this article helpful?