Contents x
b2_update_file_retention
    • Print
    • Dark
      Light
    Contents

    b2_update_file_retention

      • Print
      • Dark
        Light
      Article Summary

      Post
      /b2api/v3/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.

      PLEASE 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 writeFileRententions capability.

      Body parameters
      Expand All
      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

      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.

      Expand All
      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
      statuscodedescription
      400bad_requestThe 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.
      400metadata_exceededThis 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
      statuscodedescription
      401bad_auth_tokenThe auth token used is not valid. Call b2_authorize_account again to either get a new one, or an error message describing the problem.
      401expired_auth_tokenThe auth token used has expired. Call b2_authorize_account again to get a new one.
      403
      statuscodedescription
      403access_deniedThe 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.
      403cap_exceededUsage cap exceeded.
      405
      statuscodedescription
      405method_not_allowedThis operation is not allowed because the specified file is a "hide marker."
      Was this article helpful?
      What's Next