# 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="/pages/WzmfOMBmFA09u21qU67U#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> |


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.abyssale.com/rest-api/generation/visual-versioning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.