b2_update_file_retention
- 11 Sep 2026
- Print
- DarkLight
b2_update_file_retention
- Updated on 11 Sep 2026
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Post
/b2api/v4/b2_update_file_retention
Updates the Object Lock retention settings for an existing file
Modifies the Object Lock retention settings for an existing file. After enabling file retention for a file in an Object Lock-enabled bucket, any attempts to delete the file or make any changes to it before the end of the retention period will fail.
File retention settings can be configured in either governance or compliance mode. For files protected in governance mode, file retention settings can be deleted or the retention period shortened only by clients with the appropriate application key capability (i.e., bypassGovernance). File retention settings for files protected in compliance mode cannot removed by any user, but their retention dates can be extended by clients with appropriate application key capabilities.
NOTE:
This API endpoint can be called using a GET request by converting the parameters in the request body to query parameters.
Header parameters
Authorization
stringRequired
An account authorization token, obtained from b2_authorize_account.
The token must have the writeFileRetentions capability.
Body parameters
object
fileName
string Required
The name of the file.
Examplemyfile.txt
fileId
string Required
The ID of the file, as returned by b2_upload_file, b2_list_file_names, or b2_list_file_versions.
Example97asd9f8d98af7
fileRetention
object Required
Specifies the file retention settings for Backblaze B2 to use for this file. See Object Lock for details.
Example{ "mode": "governance", "retainUntilTimestamp": "1628942493000" }
mode
string
Valid values[ "compliance", "governance" ]
retainUntilTimestamp
integer
bypassGovernance
string
Must be specified and set to true if deleting an existing governance mode retention setting or shortening an existing governance mode retention period. See Object Lock for details.
Example
Responses
200
The request succeeded.
The response headers include the Content-Type that was specified when the file was uploaded. They also include the X-Bz-FileName and X-Bz-Content-Sha1 headers, plus X-Bz-Info-* headers for any custom file info that was provided with the upload. The X-Bz-FileName uses percent-encoding, as if it were a URL parameter.
object
fileId
string
The unique identifier for this version of this file.
Example4_h4a48fe8875c6214145260818_f000000000000472a_d20210515_m032022_c001_v0000123_t0104
fileName
string
The name of this file.
Exampletyping_test.txt
fileRetention
object
The updated file retention settings.
Example{ "isClientAuthorizedToRead": true, "value": { "mode": null, "retainUntilTimestamp": null } }
isClientAuthorizedToRead
boolean
value
object
mode
string
retainUntilTimestamp
integer
400
| status | code | description |
|---|---|---|
| 400 | bad_request | The request had the wrong fields or illegal values, or the bucket is not Object Lock-enabled. The message returned with the error will describe the problem. |
| 400 | metadata_exceeded | This operation is not allowed because of the current file metadata size. If needed, use b2_copy_file with REPLACE metadataDirective to copy the file using less metadata. Then use b2_delete_file_version to delete the original version. |
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. |
403
| status | code | description |
|---|---|---|
| 403 | access_denied | 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. |
| 403 | cap_exceeded | Usage cap exceeded. |
405
| status | code | description |
|---|---|---|
| 405 | method_not_allowed | This operation is not allowed because the specified file is a "hide marker." |
Was this article helpful?