SiteUpdate

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hypamoon-com/json-schema/hypamoon-com-site-update-schema.json",
  "title": "SiteUpdate",
  "description": "Change a site: a new name, new files, a password (or null to remove it), or a combination. The slug stays the same. The usual way: send only the changed files with keep_existing: true and if_match_version, images preferably as source_url.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hypamoon-com-openapi.json#/components/schemas/SiteUpdate",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "A name for your own overview, like the business or the page."
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Where the file lives on the site, like /index.html, /style.css or /img/logo.png. Relative paths (index.html) get a leading /."
          },
          "content": {
            "type": "string",
            "description": "The file itself: plain text for html, css, js, json, txt, xml, svg, webmanifest and md; base64 for png, jpg, gif, webp, ico, woff, woff2, pdf, mp4, webm, mp3 and m4a only when there is no URL for it (prefer source_url; a video or audio file via source_url or an upload, never base64). Leave it out for a file with source_url, or one you uploaded with create_upload_urls (POST /sites/uploads): then send sha256 and bytes."
          },
          "source_url": {
            "type": "string",
            "minLength": 9,
            "maxLength": 2048,
            "description": "Instead of content: a public https URL of the file (port 443), for images, fonts, PDFs, video and audio above all. Hypamoon fetches it once (at most 3 redirects, within the size limits of the plan) and checks it like a file sent with content. Its type must match the path (a .jpg path needs a JPEG, a .mp4 path an MP4). Leave encoding out. Use it instead of base64 whenever the file has a URL; never send a video as base64."
          },
          "encoding": {
            "type": "string",
            "enum": [
              "utf8",
              "base64"
            ],
            "description": "utf8 for text, base64 for images, fonts, PDF, video and audio. Leave it out: it follows from the file type."
          },
          "content_type": {
            "type": "string",
            "maxLength": 100,
            "description": "Leave it out: it follows from the extension (.html is text/html). Only for a path without a known extension, and only an allowed type."
          },
          "sha256": {
            "type": "string",
            "maxLength": 64,
            "description": "Only for an uploaded file, instead of content: the SHA-256 of its bytes as 64 lowercase hex characters, as you sent it to create_upload_urls."
          },
          "bytes": {
            "type": "integer",
            "minimum": 0,
            "description": "Only for an uploaded file, instead of content: its exact size in bytes."
          }
        },
        "required": [
          "path"
        ],
        "additionalProperties": false,
        "description": "One file of the site: with content, with source_url (Hypamoon fetches it), or for a large file with sha256 and bytes of an upload (create_upload_urls)."
      },
      "description": "Usually with keep_existing: true: only the files you add or change; every other file stays as it is, so never send images that are already on the site again. Without keep_existing, files is the complete new set of files: a file you leave out is removed, and the answer lists it in warnings."
    },
    "keep_existing": {
      "type": "boolean",
      "description": "true: a partial update. Only the files in files are added or replaced, delete_paths removes files, and every other file stays. Needs if_match_version. The limits, the checks and four-eyes approval apply to the whole site as it will be after the update."
    },
    "delete_paths": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "maxItems": 2000,
      "description": "Only with keep_existing: true. Paths of existing files to remove, like /old.html. A path that is not on the site is an error."
    },
    "media": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "minItems": 1,
      "maxItems": 200,
      "description": "Optional. Files from the project's media library (list_media) to put on the site, without uploading them again: folders like \"portfolio/\" (with subfolders), file ids, or paths like /media/logo.webp. Each file lands at its library path with its 640 version next to it; private originals never go on a site. A file you also send in files wins."
    },
    "if_match_version": {
      "type": "string",
      "maxLength": 64,
      "description": "The version of the site you are changing, from list_sites, get_site or the last deploy (version). Required with keep_existing. If the site changed since, you get 409 version_conflict with current_version and nothing changes: read the site again and redo your change."
    },
    "password": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 72,
      "description": "Optional. One shared password for the whole site (4 to 72 characters): visitors enter it once per browser, like password protection on a preview. Not a login system: no accounts, no per-visitor access. null or an empty string removes it. Never returned; the site shows password_protected instead."
    },
    "security_txt": {
      "type": "string",
      "enum": [
        "auto",
        "off"
      ],
      "description": "auto (default): when the site has no /.well-known/security.txt of its own, Hypamoon serves one with the project's contact address (the shop contact_email, else the billing email; none set means no file). off: no security.txt from Hypamoon. A file of your own at that path always wins."
    },
    "message": {
      "type": "string",
      "maxLength": 500,
      "description": "Optional, but always send it: what changed and why, in one short sentence (up to 200 characters), like a commit message: \"New opening hours for the summer\" or \"Spring menu, the user asked for it\". It shows in the version history; without it Hypamoon writes a short summary like \"Changed /index.html\"."
    },
    "preview": {
      "type": "boolean",
      "description": "true: do not put this change live. It becomes a preview version at a secret link (preview.url in the answer, not indexed), and the live site stays as it is. Put it live later with promote_site_version. Only files (with keep_existing as usual), no name or password. Use it for large changes the user should see first."
    },
    "confirm_replace": {
      "type": "boolean",
      "description": "Only after the user agreed. A deploy without keep_existing that removes more than half of the files, makes the site more than half smaller, or rewrites most of /index.html while other files disappear, is held as a preview instead of going live (guardrail in the answer). Send confirm_replace: true only when the user has said yes to replacing the site like that; then it goes live right away."
    }
  },
  "additionalProperties": false
}