Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"files"
],
"properties": {
"ttl": {
"type": "number",
"description": "Seconds until this deployment expires and the platform reclaims it; omit for one that never does. Only for authenticated deploys — an anonymous deployment already expires on the platform's schedule, and a requested ttl on one is refused. A deployment carrying a ttl cannot be linked to any domain: deploy without one if the site needs a domain."
},
"files": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"content"
],
"properties": {
"path": {
"type": "string",
"description": "Relative path within the site (e.g. \"index.html\", \"assets/app.css\"). No leading slash; no parent-folder wrapping."
},
"content": {
"type": "string",
"description": "File content as a plain text string. For HTML, CSS, JS, JSON, SVG, plain text — pass directly with no encoding step. For binary files (images, fonts) ONLY, set this entry's `encoding: \"base64\"` and pass base64-encoded bytes."
},
"encoding": {
"enum": [
"utf-8",
"base64"
],
"type": "string",
"description": "Defaults to `\"utf-8\"` (raw text). Set to `\"base64\"` ONLY for binary files. Never base64-encode text content — pass it as a plain string."
}
}
},
"description": "Files that make up the site. The site root is implied by these paths."
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "Labels for organizing deployments (e.g. [\"env:production\", \"v1.2\"]). Each is a word, or a key and a value split by one \":\". Lowercase, 3-63 chars, allows . _ - inside a word. Up to 10."
},
"password": {
"type": "string",
"description": "Optional password to gate the deployment behind an unlock prompt (6–128 characters; whitespace significant). Visitors must enter this password before viewing the site, including on any custom domains pointing at it."
},
"idempotencyKey": {
"type": "string",
"description": "Makes this deploy replayable instead of repeatable. A deploy is not naturally idempotent: if a call times out you cannot tell \"it never landed\" from \"it landed and the response was lost\", and retrying creates a second deployment. Send the same key on the retry and you get back the deployment the first try made, if it went live in the last 24 hours. A key works only within the account that sent it: without an account it is ignored, and a retry deploys again. Key the ATTEMPT (a run id, a commit sha, a uuid minted before the first try), never one minted fresh on each retry, which would defeat the point."
}
}
}