b2_update_file_legal_hold
- 11 Sep 2026
- Print
- DarkLight
b2_update_file_legal_hold
- 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_legal_hold
Modifies the Object Lock legal hold status for an existing file
Used to enable legal hold for a file in an Object Lock-enabled bucket, preventing it from being deleted, or to disable legal hold protections for a file.
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 writeFileLegalHolds 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.
Example4_h4a48fe8875c6214145260818_f000000000000472a_d20210515_m032022_c001_v0000123_t0104
legalHold
string Required
on to enable legal hold for the file, off to disable it.
Valid values[ "on", "off" ]
Exampleon
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
legalHold
string
The updated value of the legal hold status, indicating whether the file has a legal hold in place.
Exampleon
400
| status | code | description |
|---|---|---|
| 400 | bad_request | The request had the wrong fields or illegal values. 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?