When a soft-deleted object is restored, a new copy of that object is created in the same bucket
and inherits the same metadata as the soft-deleted object. The inherited metadata is the metadata
that existed when the original object became soft deleted, with the following exceptions:
ThecreateTimeof the new object is set to the time at which the soft-deleted
object was restored.
ThesoftDeleteTimeandhardDeleteTimevalues are cleared.
A new generation is assigned and the metageneration is reset to 1.
If the soft-deleted object was in a bucket that had Autoclass enabled, the new object is
restored to Standard storage.
The restored object inherits the bucket's default object ACL, unlesscopySourceAclistrue.
If a live object using the same name already exists in the bucket and becomes overwritten,
the live object becomes a noncurrent object ifObject Versioningis enabled on the bucket. If
Object Versioning is not enabled, the live object becomes soft deleted.
Required permissions
The authenticated user must have the following IAM permissions to use this
method:
storage.objects.restore
storage.objects.create
storage.objects.delete(only required if overwriting an existing object)
storage.objects.getIamPolicy(only required ifprojectionisfulland
the relevant bucket hasuniform bucket-level
accessdisabled)
storage.objects.setIamPolicy(only required ifcopySourceAclistrueand the relevant bucket hasuniform
bucket-level accessdisabled)
Request
HTTP request
POST https://storage.googleapis.com/storage/v1/b/bucket/o/object/restore
To see an example of how to include query parameters in a request, see theJSON API Overviewpage.
Parameters
Parameter name
Value
Description
Path parameters
bucket
string
Name of the bucket in which the new object will be created. Must be the same bucket
that contained the soft-deleted object being restored.
object
string
Name of the soft-deleted object to restore. For information about how to URL encode object
names to be path safe, seeEncoding URI path parts.
Required query parameters
generation
long
Specifies the version of the soft-deleted object to restore.
Optional query parameters
copySourceAcl
boolean
Applicable only for buckets that don't haveuniform bucket-level accessenabled. Iftrue, copies the soft-deleted object's ACL and applies it to the
restored object. Iffalseor not specified, the restored object inherits
the bucket's default object ACL.
ifGenerationMatch
long
Makes the operation conditional on there being a live version of the object with a
generation number that matches the given value. SettingifGenerationMatchto
0 makes the operation succeed only if there is no such live object.
ifGenerationNotMatch
long
Makes the operation conditional on there being a live version of the object with a
generation number that does not match the given value. If no live object exists, the
precondition fails. SettingifGenerationNotMatchto 0 makes the operation
succeed if there is a live version of the object.
ifMetagenerationMatch
long
Makes the operation conditional on there being a live version of the object with a
metageneration number that matches the given value.
ifMetagenerationNotMatch
long
Makes the operation conditional on there being a live version of the object with a
metageneration number that does not match the given value.
When restoring a soft-deleted object, therestoreTokenis only
required when thenameandgenerationvalues of the objectdo not uniquely
identify it. Otherwise, including arestoreTokenin the request is
optional.
Request body
Do not supply a request body with this method.
Response
If successful, this method returns anobject resourcein the response
body.
The following errors could occur:
If the specified bucket in the request does not have a soft delete policy, the request fails
with a400 Bad Requesterror with the reasonSoftDeletePolicyRequired.
If the soft-deleted object's retention duration has passed, or the soft-deleted
object no longer exists, the request fails with a404 Not Founderror with the reasonnotFound.
If the specified object in the request is not a soft-deleted object but is either live or
noncurrent, the request fails with a412 Failed Preconditionerror with the reasonobjectNotSoftDeleted.
If the specified object in the request belongs to a bucket that has aBucket Lock retention policy, where the object's age is
less than the retention duration, the request fails with a403 Forbiddenerror
with the reasonretentionPolicyNotMet.
For more information about status and error codes returned by this API, see thereference page.
Try it!
Use the APIs Explorer below to call this method on live data and see the response.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Objects: restore\n\nRestores a [soft-deleted object](/storage/docs/soft-delete).\n\nWhen a soft-deleted object is restored, a new copy of that object is created in the same bucket\nand inherits the same metadata as the soft-deleted object. The inherited metadata is the metadata\nthat existed when the original object became soft deleted, with the following exceptions:\n\n- The `createTime` of the new object is set to the time at which the soft-deleted object was restored.\n- The `softDeleteTime` and `hardDeleteTime` values are cleared.\n- A new generation is assigned and the metageneration is reset to 1.\n- If the soft-deleted object was in a bucket that had Autoclass enabled, the new object is restored to Standard storage.\n- The restored object inherits the bucket's default object ACL, unless `copySourceAcl` is `true`.\n\n\u003cbr /\u003e\n\nIf a live object using the same name already exists in the bucket and becomes overwritten,\nthe live object becomes a noncurrent object if\n[Object Versioning](/storage/docs/object-versioning) is enabled on the bucket. If\nObject Versioning is not enabled, the live object becomes soft deleted.\n\nRequired permissions\n--------------------\n\nThe authenticated user must have the following IAM permissions to use this\nmethod:\n\n- `storage.objects.restore`\n- `storage.objects.create`\n- `storage.objects.delete` (only required if overwriting an existing object)\n- `storage.objects.getIamPolicy` (only required if `projection` is `full` and the relevant bucket has [uniform bucket-level\n access](/storage/docs/uniform-bucket-level-access) disabled)\n- `storage.objects.setIamPolicy` (only required if `copySourceAcl` is `true` and the relevant bucket has [uniform\n bucket-level access](/storage/docs/uniform-bucket-level-access) disabled)\n\n\u003cbr /\u003e\n\nRequest\n-------\n\n### HTTP request\n\n```\nPOST https://storage.googleapis.com/storage/v1/b/bucket/o/object/restore\n```\n\nIn addition to [standard query parameters](/storage/docs/json_api/v1/parameters#query),\nthe following query parameters apply to this method.\n\nTo see an example of how to include query parameters in a request, see the\n[JSON API Overview](/storage/docs/json_api#query_parameters) page.\n\n### Parameters\n\n### Request body\n\nDo not supply a request body with this method.\n\nResponse\n--------\n\nIf successful, this method returns an\n[object resource](/storage/docs/json_api/v1/objects#resource) in the response\nbody.\n\nThe following errors could occur:\n\n- If the specified bucket in the request does not have a soft delete policy, the request fails with a `400 Bad Request` error with the reason `SoftDeletePolicyRequired`.\n- If the soft-deleted object's retention duration has passed, or the soft-deleted object no longer exists, the request fails with a `404 Not Found` error with the reason `notFound`.\n- If the specified object in the request is not a soft-deleted object but is either live or noncurrent, the request fails with a `412 Failed Precondition` error with the reason `objectNotSoftDeleted`.\n- If the specified object in the request belongs to a bucket that has a [Bucket Lock retention policy](/storage/docs/bucket-lock), where the object's age is less than the retention duration, the request fails with a `403 Forbidden` error with the reason `retentionPolicyNotMet`.\n\n\u003cbr /\u003e\n\nFor more information about status and error codes returned by this API, see the\n[reference page](/storage/docs/json_api/v1/status-codes).\n\nTry it!\n-------\n\nUse the APIs Explorer below to call this method on live data and see the response."]]
