> For the complete documentation index, see [llms.txt](https://clients.medianova.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://clients.medianova.com/products/object-storage-stook/bucket-configuration/versioning.md).

# Versioning

Preserve previous versions of objects in a Stook Bucket and recover overwritten or deleted data.

Configure Versioning to preserve previous versions of objects when they are overwritten or deleted in a Stook Bucket.

Versioning provides three modes: **Off**, **On**, and **Suspended**. When Versioning is enabled, previous object versions remain available until they are permanently deleted.

{% hint style="warning" %}
After Versioning has been enabled, it cannot be switched back to **Off**. You can set it to **Suspended**, which stops creating new versions while preserving existing versions.
{% endhint %}

{% hint style="info" %}
For complete request parameters, response schemas, and error responses, see [Bucket Settings API](/api-documentation/object-storage-stook/buckets/settings.md).
{% endhint %}

## How Versioning Works

Versioning supports the following modes:

<table><thead><tr><th width="166.800048828125">Mode</th><th>Behavior</th></tr></thead><tbody><tr><td><strong>Off</strong></td><td>Overwrites the previous copy of an object.</td></tr><tr><td><strong>On</strong></td><td>Preserves previous versions when objects are overwritten or deleted.</td></tr><tr><td><strong>Suspended</strong></td><td>Stops creating new versions while preserving existing versions.</td></tr></tbody></table>

Previous object versions consume storage capacity while they remain in the Stook Bucket.

When a versioned object is deleted without specifying a version ID, the object is hidden by a delete marker. Previous versions remain stored and can be restored.

## Versioning Dependencies

Versioning must be **On** to use:

* [MFA Delete](/products/object-storage-stook/bucket-configuration/mfa-delete.md)
* [Object Lock](/products/object-storage-stook/bucket-configuration/object-lock.md)

{% hint style="warning" %}
Versioning cannot be suspended while **MFA Delete** or **Object Lock** is enabled.
{% endhint %}

## Configure Versioning

{% stepper %}
{% step %}

### **Open the Stook Bucket**

In the [Medianova Control Panel](https://cloud.medianova.com), select **Stook Object Storage → Buckets**, then select the Stook Bucket you want to configure.
{% endstep %}

{% step %}

### **Open Versioning**

On the **Bucket configuration** page, select **Versioning**.

<figure><img src="https://542970813-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtK7oIwmhUHdEJcaH4Hx8%2Fuploads%2F2KrWsxEnqEHrs7aR6YGS%2Fimage.png?alt=media&amp;token=3d4e19a7-f1b8-4064-80c4-5845f90f5654" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### **Select the Versioning mode**

Select one of the available modes:

* **Off** — overwrite the previous copy.
* **On** — keep every previous version.
* **Suspended** — stop creating new versions while keeping existing versions.
  {% endstep %}

{% step %}

### **Save the configuration**

Select **Save Changes**.
{% endstep %}
{% endstepper %}

## Work with Object Versions

Use an S3-compatible client, such as the AWS CLI, to list, download, restore, and permanently delete object versions.

{% hint style="info" %}
Listing object versions and downloading an earlier version require the master key or an access key with **All S3 Actions**. The **Versioning** permission category does not include these actions.

Permanently removing an object version requires the **Delete Object Version** permission. See Manage Access Keys.
{% endhint %}

### List Object Versions

```bash
aws s3api --endpoint-url https://<ENDPOINT_URL> \
  list-object-versions \
  --bucket <BUCKET_NAME> \
  --prefix <OBJECT_KEY>
```

This command lists the stored versions and delete markers associated with the specified object key.

### Download an Earlier Version

```bash
aws s3api --endpoint-url https://<ENDPOINT_URL> \
  get-object \
  --bucket <BUCKET_NAME> \
  --key <OBJECT_KEY> \
  --version-id <VERSION_ID> \
  <LOCAL_FILE>
```

This command downloads the specified object version to the local file path without changing the current version stored in the Stook Bucket.

### Restore a Deleted Object

A deleted object is hidden by a delete marker. To restore the object, identify the delete marker with `list-object-versions`, then remove that delete marker:

```bash
aws s3api --endpoint-url https://<ENDPOINT_URL> \
  delete-object \
  --bucket <BUCKET_NAME> \
  --key <OBJECT_KEY> \
  --version-id <DELETE_MARKER_VERSION_ID>
```

This command permanently removes the specified delete marker. Removing the delete marker makes the previous object version available again.

### Permanently Delete an Object Version

```bash
aws s3api --endpoint-url https://<ENDPOINT_URL> \
  delete-object \
  --bucket <BUCKET_NAME> \
  --key <OBJECT_KEY> \
  --version-id <VERSION_ID>
```

This command permanently removes the specified object version. The deleted version cannot be recovered.

{% hint style="warning" %}
If **MFA Delete** is enabled, permanently deleting an object version or removing a delete marker also requires a code from the configured authenticator.
{% endhint %}

## Configure Versioning with the API

Use the bucket settings endpoint to configure Versioning:

```http
PATCH /api/v2/stook/{organization_uuid}/bucket/{bucket_uuid}/settings
```

To enable Versioning, send:

```json
{
  "versioning": "enabled"
}
```

The `versioning` field supports the following values:

| API value     | Mode      |
| ------------- | --------- |
| `unversioned` | Off       |
| `enabled`     | On        |
| `suspended`   | Suspended |

After Versioning has been enabled, `unversioned` can no longer be used for the Stook Bucket. Use `suspended` to stop creating new versions.

## Troubleshooting

### Versioning cannot be switched off

After Versioning has been enabled, it cannot return to **Off**.

Select **Suspended** instead. Existing versions remain available, but new versions are no longer created.

### Versioning cannot be suspended while Object Lock is enabled

Object Lock requires Versioning to remain **On**.

Versioning cannot be suspended while Object Lock is enabled on the Stook Bucket.

### Versioning cannot be suspended while MFA Delete is enabled

Disable **MFA Delete** before suspending Versioning.

Disabling MFA Delete requires a valid code from the configured authenticator.

## Related Topics

* [Bucket Configuration](/products/object-storage-stook/bucket-configuration.md)
* [MFA Delete](/products/object-storage-stook/bucket-configuration/mfa-delete.md)
* [Object Lock](/products/object-storage-stook/bucket-configuration/object-lock.md)
* [Manage Access Keys](/products/object-storage-stook/manage-access-keys.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://clients.medianova.com/products/object-storage-stook/bucket-configuration/versioning.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.