# Visual Versioning

Visual Versioning allows you to update a previously generated visual without changing its unique `sharing_id`. This is essential for maintaining consistent external links while tracking iterative changes internally. When you create a new version of a visual, the version number is incremented, and the older version is retained in your history.

### 1. How Versioning Works

Versioning is achieved by referencing an existing visual during a new generation request.

* Request Input: You pass the `id` of the visual you wish to update in the new generation request.
* Version Increment: Abyssale creates a new visual asset with a new `id` but keeps the original `sharing_id`. The new visual's `version` property is incremented by +1 *(compared to the last existing version related to the sharing\_id)*.
* URLs: The original `view_url` and any sharing links associated with the `sharing_id` will now display the newly generated visual (the latest version).

### 2. API Configuration

To create a new visual version, include the `original_visual_id` property in your generation request body.

| `original_visual_id` | `string` (UUID v4) | The `id` of the existing visual you want to create a new version for. |
| -------------------- | ------------------ | --------------------------------------------------------------------- |

#### Example: Synchronous Generation Request

```
POST https://api.abyssale.com/banner-builder/{designId}/generate
```

```json
{
  "original_visual_id": "a14e1d26-ff41-47cb-bbf9-8f2d777a5bd7",
  "elements": {
    "text_field": {
      "payload": "Updated Content for V2"
    }
  }
}
```

### 3. Constraints on Versioning

Due to the nature of version tracking, versioning is subject to the following limitations based on the generation method:

| Synchronous API  | None                                                                                                                                                                                                                                                                                           |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Asynchronous API | <p>The asynchronous batch request must be limited to generating a single visual, and the format specified in the request must match the format of the original visual.<br><br>If the request payload generates multiple visuals, <strong>the versioning request will be rejected.</strong></p> |

### 4. Response Payload Properties

When a visual is generated as a new version, the response payload will include or update the following properties:

| `id`         | This is a new UUID, unique to this specific version of the visual.                                                                                                                                                                                                          |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sharing_id` | This ID remains the same as the `original_visual_id` provided in the request. It links all versions together.                                                                                                                                                               |
| `version`    | This number is incremented (e.g., from `1` to `2`).                                                                                                                                                                                                                         |
| `view_url`   | <p>If returned (<a href="../../../webhooks/events/banner-events#optional-properties-visual-url-properties">look at the related documentation</a>):<br>The URL associated with the <code>sharing\_id</code> will automatically point to this new, latest visual version.</p> |