# Restore an earlier version

List the versions and delete markers of a versioned bucket, make an older version current again, undelete an object, or delete one version for good.

This works in a bucket with versioning on (see [Turn on versioning](turn-on-versioning.md)).
Replace _example-uploads_ with your bucket's name, _report.pdf_ with the object's key and
_3HL4kqtJlcpXroDTDmJ-rmSpXd3dIbrHY_ with the version id.

## Prerequisites

- To list versions: `s3:ListBucketVersions`.
- To download an older version: `s3:GetObjectVersion`.
- To make a version current: `s3:PutObject` and `s3:GetObjectVersion`.
- To delete a version or a delete marker for good: `s3:DeleteObjectVersion`.
- In the console, also `s3:GetBucket` on the bucket to open it (without it the bucket's page says
  "Access denied").

## List the versions

**Console**
1. Open the bucket, then choose **Objects**, and open the folder.
2. Turn on **Show versions**. Each entry is marked **Current**, **Older** or **Delete marker**.
   Choose **Show more** for the next 200.

**CLI**
```sh
dcloud s3 bucket-objects list-versions example-uploads --prefix reports/
```

**API**
```http
GET /s3/api/buckets/example-uploads/objects/versions?prefix=reports/
```

The answer lists 200 at a time, newest first per key; pass `nextKeyMarker` and
`nextVersionIdMarker` back as `keyMarker` and `versionIdMarker` for the next page.

## Make an older version current

**Console**
1. With **Show versions** on, open the older version's menu.
2. Choose **Make current**.

The console says "report.pdf: the version of _date_ is current again."

**CLI**
```sh
dcloud s3 bucket-objects restore-version example-uploads --key report.pdf \
  --version-id 3HL4kqtJlcpXroDTDmJ-rmSpXd3dIbrHY
```

**API**
```http
POST /s3/api/buckets/example-uploads/objects/restore-version
{ "key": "report.pdf", "versionId": "3HL4kqtJlcpXroDTDmJ-rmSpXd3dIbrHY" }
```

The version is copied over its key as a new latest version; the older version stays. Over S3,
`aws s3api copy-object` with `--copy-source example-uploads/report.pdf?versionId=…` does the same.

## Undelete an object

A delete in a versioned bucket adds a delete marker that hides the object. Removing the marker
brings it back.

**Console**
1. With **Show versions** on, open the menu of the current **Delete marker**.
2. Choose **Undelete**.

**CLI**
```sh
dcloud s3 bucket-objects delete-versions example-uploads \
  --versions '{"key":"report.pdf","versionId":"3HL4kqtJlcpXroDTDmJ-rmSpXd3dIbrHY"}'
```

**API**
```http
POST /s3/api/buckets/example-uploads/objects/delete-versions
{ "versions": [{ "key": "report.pdf", "versionId": "3HL4kqtJlcpXroDTDmJ-rmSpXd3dIbrHY" }] }
```

Name the delete marker's version id.

## Delete one version for good

In the console, choose **Delete this version for good** in the version's menu, then **Delete** in
the dialog **Delete this version for good?**.
Over the CLI and API, `delete-versions` with that version's id, as above; up to 1000 versions per
call. Without `s3:DeleteObjectVersion` on any one of the keys, the whole request is refused with
`403`. Otherwise the answer lists what was deleted and, under `errors`, each version the bucket
refused.

## Download an older version

In the console, choose **Download this version**. Over the API,
`POST /s3/api/buckets/example-uploads/objects/download-url` with `key` and `versionId` answers a
URL valid for 15 minutes.

## Related

- [Turn on versioning](turn-on-versioning.md)
- [Set lifecycle rules](set-lifecycle-rules.md)
- `s3.bucket-objects.restore-version` · `dcloud s3 bucket-objects restore-version`
