Topolo Docs Topolo Platform
Open workspace

List saved site versions

List saved immutable versions for a site in the active workspace.

List saved site versions

Every worked value below is SYNTHETIC / UNRUN; no action was called.

List the site's saved versions, which are what a restore can return to.

Request

  • Action: app_topolo_web.sites.versions.list
  • Method and path: GET /api/studio/sites/{siteId}/versions
  • Required permission: app_topolo_web.studio:read
  • Input: {"siteId":"site_synth_01"}
  • Additional input fields: false

How it behaves

Read-only version-history lookup for one site. Returns the version records selected by organization, workspace and site ID. D1 source queries published_at DESC; the in-memory path returns the filtered stored array as-is. The route does not check site existence, so an absent/out-of-scope site yields an empty list rather than a site-not-found response. Each version has immutable snapshot content and may be selected for restore only when it belongs to this site.

Worked examples

SYNTHETIC / UNRUN — saved versions for one site

HTTP 200; response body (synthetic/unrun):

[
  {
    "id": "version_synth_02",
    "organizationId": "org_synth_01",
    "workspaceId": "workspace_synth_01",
    "siteId": "site_synth_01",
    "versionNumber": 2,
    "label": "Updated service copy",
    "snapshot": {
      "intent": "business_site",
      "siteTitle": "Northstar Studio",
      "siteDescription": "A fictional service studio offering careful launch planning.",
      "contactEmail": "hello@example.invalid",
      "navigation": [],
      "footerNavigation": [],
      "menus": [],
      "styleClasses": [],
      "theme": {
        "primary": "#111111",
        "secondary": "#333333",
        "surface": "#ffffff",
        "ink": "#111111",
        "muted": "#444444",
        "accent": "#005fcc",
        "accentSoft": "#111111",
        "glow": "#111111",
        "headingFont": "Inter, system-ui, sans-serif",
        "bodyFont": "Inter, system-ui, sans-serif",
        "radius": "16px"
      },
      "document": {
        "version": 1,
        "pages": [
          {
            "id": "page-home",
            "kind": "page",
            "pageId": "page-home",
            "label": "Home",
            "path": [
              "page-home"
            ],
            "source": {
              "kind": "page",
              "id": "page-home"
            },
            "value": {
              "id": "page-home",
              "slug": "/",
              "title": "Northstar Studio",
              "description": "A fictional service studio offering careful launch planning."
            },
            "children": [
              {
                "kind": "slot",
                "slotKind": "page-body",
                "id": "page-home:body",
                "pageId": "page-home",
                "label": "Page body",
                "path": [
                  "page-home",
                  "slot:body"
                ],
                "parentNodeId": "page-home",
                "source": {
                  "kind": "page",
                  "id": "page-home"
                },
                "accepts": [
                  "layout",
                  "block"
                ],
                "children": [
                  {
                    "kind": "block",
                    "id": "hero-home",
                    "pageId": "page-home",
                    "label": "A clear service path",
                    "path": [
                      "page-home",
                      "slot:body",
                      "sections:0"
                    ],
                    "source": {
                      "kind": "section",
                      "id": "hero-home"
                    },
                    "blockKind": "hero",
                    "sectionKind": "hero",
                    "sectionId": "hero-home",
                    "value": {
                      "id": "hero-home",
                      "kind": "hero",
                      "title": "A clear service path",
                      "body": "The current fictional draft includes a revised service description.",
                      "primaryAction": {
                        "label": "Contact Northstar",
                        "href": "mailto:hello@example.invalid",
                        "linkKind": "custom",
                        "targetBlank": false
                      }
                    },
                    "children": []
                  }
                ]
              }
            ]
          }
        ]
      },
      "collections": [],
      "codeSnippets": [],
      "seo": {
        "metaTitle": "Northstar Studio | Example",
        "metaDescription": "A fictional service studio for example.invalid readers."
      }
    },
    "previewToken": "published-preview-synth-02",
    "publishedAt": "2026-10-22T12:00:00.000Z"
  },
  {
    "id": "version_synth_01",
    "organizationId": "org_synth_01",
    "workspaceId": "workspace_synth_01",
    "siteId": "site_synth_01",
    "versionNumber": 1,
    "label": "Initial publish",
    "snapshot": {
      "intent": "business_site",
      "siteTitle": "Northstar Studio",
      "siteDescription": "A fictional service studio offering careful launch planning.",
      "contactEmail": "hello@example.invalid",
      "navigation": [],
      "footerNavigation": [],
      "menus": [],
      "styleClasses": [],
      "theme": {
        "primary": "#111111",
        "secondary": "#333333",
        "surface": "#ffffff",
        "ink": "#111111",
        "muted": "#444444",
        "accent": "#005fcc",
        "accentSoft": "#111111",
        "glow": "#111111",
        "headingFont": "Inter, system-ui, sans-serif",
        "bodyFont": "Inter, system-ui, sans-serif",
        "radius": "16px"
      },
      "document": {
        "version": 1,
        "pages": [
          {
            "id": "page-home",
            "kind": "page",
            "pageId": "page-home",
            "label": "Home",
            "path": [
              "page-home"
            ],
            "source": {
              "kind": "page",
              "id": "page-home"
            },
            "value": {
              "id": "page-home",
              "slug": "/",
              "title": "Northstar Studio",
              "description": "A fictional service studio offering careful launch planning."
            },
            "children": [
              {
                "kind": "slot",
                "slotKind": "page-body",
                "id": "page-home:body",
                "pageId": "page-home",
                "label": "Page body",
                "path": [
                  "page-home",
                  "slot:body"
                ],
                "parentNodeId": "page-home",
                "source": {
                  "kind": "page",
                  "id": "page-home"
                },
                "accepts": [
                  "layout",
                  "block"
                ],
                "children": [
                  {
                    "kind": "block",
                    "id": "hero-home",
                    "pageId": "page-home",
                    "label": "A clear service path",
                    "path": [
                      "page-home",
                      "slot:body",
                      "sections:0"
                    ],
                    "source": {
                      "kind": "section",
                      "id": "hero-home"
                    },
                    "blockKind": "hero",
                    "sectionKind": "hero",
                    "sectionId": "hero-home",
                    "value": {
                      "id": "hero-home",
                      "kind": "hero",
                      "title": "A clear service path",
                      "body": "A fictional team can plan a launch with careful review.",
                      "primaryAction": {
                        "label": "Contact Northstar",
                        "href": "mailto:hello@example.invalid",
                        "linkKind": "custom",
                        "targetBlank": false
                      }
                    },
                    "children": []
                  }
                ]
              }
            ]
          }
        ]
      },
      "collections": [],
      "codeSnippets": [],
      "seo": {
        "metaTitle": "Northstar Studio | Example",
        "metaDescription": "A fictional service studio for example.invalid readers."
      }
    },
    "previewToken": "published-preview-synth-01",
    "publishedAt": "2026-10-20T12:00:00.000Z"
  }
]

SYNTHETIC / UNRUN — absent site has no version rows in this scoped query

HTTP 200; response body (synthetic/unrun):

[]

Errors and recovery

The descriptor lists generic authentication, permission, rate-limit, input and dependency errors. Unlike sites.get, the route directly returns the loaded list and has no 404 wrapper. If the list is empty, confirm site/workspace scope with sites.list and sites.get. Use a version ID from this same response; do not infer a missing site solely from an empty version list.

Who should use this guide

For operators comparing saved versions before recovery. Typed guide is useful to agents selecting a same-site version; the descriptor outputSchema allows raw-array or envelope forms and weakly types each item as a generic site record, while this route returns the raw version array.

Provenance and change log

Pinned d9 source d9c75819abedaf71f9436a1d200015883a291072 (tree 186133adb5823723307184dcbd77acb1814317a1) plus the exact saved action descriptor in the current detailed catalog. The action metadata in the saved detailed catalog is bound by SHA-256 0d37dbcd6b71ee45f4e09d2a34dcb8331676dd2c0ea2184460400ec1abe688fc. Relevant implementation paths at revision d9c75819abedaf71f9436a1d200015883a291072: apps/api/src/routes/studio.ts:754-759, apps/api/src/repositories/store/sites.ts:951-952, apps/api/src/repositories/store/persistence.ts:642-649. Current-source freshness beyond the saved d9/release association is UNKNOWN; this is not fresh production action readback.

Change log — 2026-10-23 — source-derived guide content: aligned method/path/permission and input to the saved current descriptor; added synthetic/unrun branch examples; documented raw-array versus envelope schema alternatives, weak item typing, source behavior, and recovery.

Unresolved: The route-localized not-found text and provider-side reconciliation outcome are not verified by execution. Exact auth error envelopes are not claimed.