Skip to navigation

Versions

IcePanel uses a versioning system to let you maintain a live working model while also capturing point-in-time snapshots for communication and history.

The latest version

Every landscape has a special version with the ID latest. This is the live version where you make changes through the IcePanel UI or the API.

Use latest in any version-scoped endpoint:

GET /landscapes/{landscapeId}/versions/latest/model/objects
POST /landscapes/{landscapeId}/versions/latest/model/objects

Version snapshots

A version snapshot is an immutable copy of the model at a point in time. Snapshots are useful for:

  • Marking a release or milestone
  • Sharing a stable view of the architecture with stakeholders
  • Reverting to a known-good state

Create a snapshot from the current state of latest:

POST
/v1/landscapes/:landscapeId/versions
import { IcePanelClient } from "@icepanel/sdk";
async function main() {
    const client = new IcePanelClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.versions.create({
        landscapeId: "landscapeId",
        body: {
            modelHandleId: "string",
            name: "string",
            notes: "string",
        },
    });
}
main();
Try it

Required fields:

FieldDescription
nameVersion name, e.g. v2.4.0 or Q3 2025
notesDescription of what changed in this version
modelHandleIdThe handleId of the root model object to snapshot

Once created, a snapshot version is read-only. Its ID is a system-generated string (not latest).

List all versions for a landscape:

GET
/v1/landscapes/:landscapeId/versions
import { IcePanelClient } from "@icepanel/sdk";
async function main() {
    const client = new IcePanelClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.versions.list({
        landscapeId: "landscapeId",
    });
}
main();
Try it

Version reverts

Roll back a landscape to the state captured in a previous snapshot:

POST
/v1/landscapes/:landscapeId/version/reverts
import { IcePanelClient } from "@icepanel/sdk";
async function main() {
    const client = new IcePanelClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.versions.reverts.create({
        landscapeId: "landscapeId",
        body: {
            notes: "string",
            versionId: "string",
        },
    });
}
main();
Try it

Required fields:

FieldDescription
versionIdThe snapshot to revert to
notesReason for the revert

A revert creates a new entry in the revert history and replaces the latest version with the snapshot state. The snapshot itself is not modified.