---
title: "Label a version"
method: PUT
path: "/sites/{id}/versions/{versionId}/label"
tags: ["Sites"]
---

# Label a version

`PUT /sites/{id}/versions/{versionId}/label`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/sites/{id}/versions/{versionId}/label`
- 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:write`)

Gives a version a name, like "before launch", unique per site. A labeled version is kept beyond the plan's retention period; the plan sets how many labels a site can have. label null removes it.

## Path parameters

- `id` string, uuid, required
- `versionId` string, uuid, required

## Request body

- object: The label of a version.
  - `label` string, nullable, required: A name for this version, like "before launch" (1 to 60 characters, unique per site). null or an empty string removes it.

## Response `200`

The version with its label.

- object: One version of a site: a snapshot of its files.
  - `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.

## Other responses

- `400`: Bad Request: invalid_json.
- `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.
- `409`: Conflict: conflict.
- `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)