---
title: "List the versions of a site"
method: GET
path: "/sites/{id}/versions"
tags: ["Sites"]
---

# List the versions of a site

`GET /sites/{id}/versions`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/sites/{id}/versions`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.hypamoon.com/oauth/authorize`, token URL `https://api.hypamoon.com/oauth/token`, scopes: `sites:read`)

The history of a site, newest first: every deploy that changed its files (including partial deploys, imports, approved deploys, rollbacks and promoted previews) is a version with who made it, through which client, its message and the changed paths. Previews are in the list too (preview: true, with preview_url). Versions older than the plan's retention period are removed, unless they have a label or are a checkpoint (auto_label "before big change"). auto_label also marks versions that stayed live for at least 24 hours and were not rolled back ("stable"). Included on every plan; the plan sets the retention period and the number of labels.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `limit` integer
- `cursor` integer

## Response `200`

The versions, newest first.

- object: The versions of a site, newest first.
  - `object` 'list', required
  - `data` object[], required
    - `object` 'site_version', required
    - `id` string, uuid, required: The id of the version: use it for get_site_diff, rollback_site, promote_site_version and label_site_version.
    - `number` integer, required: The number of the version within the site: 1, 2, 3 and so on.
    - `site_id` string, uuid, required
    - `created_at` string, required: When this version was made (ISO 8601).
    - `cause` 'baseline' | 'deploy' | 'partial_deploy' | 'import' | 'approved_deploy' | 'rollback' | 'promote' | 'preview' | 'file_restore', required: What made it: a deploy, a partial deploy (keep_existing), an import, a deploy after four-eyes approval, a rollback, a promoted preview, a preview, a few files restored from an older version (file_restore), or baseline (how the site was when its history started).
    - `message` string, nullable, required: The message sent with the deploy, if any.
    - `author` object, required: Who made it, and through which client.
      - `user_id` string, nullable, required
      - `via` 'portal' | 'api_key' | 'connected_app' | 'system', required
      - `client` 'chatgpt' | 'claude' | 'api' | 'portal' | 'wizard' | 'other', required
      - `client_name` string, nullable, required
    - `changes` object, required: The paths that changed compared to the version before.
      - `added` string[], required
      - `modified` string[], required
      - `removed` string[], required
      - `counts` object, required
        - `added` integer, required
        - `modified` integer, required
        - `removed` integer, required
      - `truncated` boolean, required: true: the lists show the first 50 paths per kind; get_site_diff has all.
    - `files` integer, required
    - `bytes` integer, required
    - `current` boolean, required: true for the version that is live now.
    - `preview` boolean, required: true for a preview that never went live.
    - `preview_url` string, nullable, required: The secret address of a preview (not indexed). Share it only with people who should see it.
    - `label` string, nullable, required
    - `labeled_at` string, nullable, required
    - `restored_from` string, uuid, nullable, required: For a rollback or promote: the version it came from.
    - `expires_at` string, nullable, required: When the retention of the plan removes it; null for the current version, labeled versions and checkpoints.
    - `auto_label` 'before big change' | 'stable' | 'held by guardrail' | 'null', nullable, required: A marker Hypamoon sets itself, apart from label: "before big change" is the version that was live when a deploy hit the guardrail (kept like a labeled version), "stable" a version that stayed live for at least 24 hours and was not rolled back (both good versions to go back to), and "held by guardrail" a preview the guardrail made instead of putting a deploy live.
  - `has_more` boolean, required
  - `next_cursor` integer, nullable, required: Send as cursor for the next page.
  - `retention_days` integer, required: How long the plan keeps versions.
  - `labels_max` integer, required: How many labeled versions a site can have on this plan.

## Other responses

- `401`: Unauthorized: unauthorized, missing_api_key, invalid_api_key, api_key_revoked, project_deleted.
- `402`: Payment Required: plan_limit_reached.
- `403`: Forbidden: project_not_enabled, key_mode_mismatch, missing_scope, verification_required.
- `404`: Not Found: not_found.
- `422`: Unprocessable Content: validation_failed.
- `429`: Too Many Requests: rate_limited.
- `500`: Internal Server Error: internal_error.
- `503`: Service Unavailable: service_unavailable.

---

[API](https://skmtc.dev/hypamoon/apis/hypamoon-api.md) · [All operations](https://skmtc.dev/hypamoon/apis/hypamoon-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hypamoon/apis/hypamoon-api/revisions/9f0b90004c06?raw)