Upload a Deploy
Upload a new version of a static app as a .zip of built files (with index.html at the publish-dir root). The archive is staged and a build job is enqueued; the build runs asynchronously in the background. Send multipart/form-data with a single file field.
For a fullstack app, zip the whole project: the backend at the root and the front end in its own folder — the output folder of a build Ngris runs (dist/, build/, out/…) or, with no build, public/ (or the app's publish_dir). Only that folder is published. Without one the deploy fails (its error says why) and nothing is published — see Full-stack project layout.
Request (multipart/form-data)
.zip of your site — source (Ngris builds it) or built files. At most 100 MB per upload; the account's storage quota applies too.v2.1.0. When unset the display falls back to the git commit short SHA (git deploys) or v{n} (uploads).true the build goes live once it's ready (the normal behaviour). Pass a falsey value (false, 0, no, off) to build a candidate instead: it still builds, but production is untouched — turn on its preview URL to check it, then promote it when you're ready. When omitted: true, or false when the app has require_manual_promotion on.Per-app environment variables are injected into the build; watch it live via the build log.
Response (202 Accepted)
The new deploy, with the deploy fields of the list except the list-only preview_url, display_version, pruned and rollbackable:
{deploy_uuid} of activate and the build log).upload.queued — poll the list until it reaches ready.false for a candidate (see activate).Deprecated: until the sunset deploy objects also carry the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.
Errors
file (400) or a body over the size limit or not valid multipart (413).quota_paused).failed. Retry.List Deploys
List an app's deploys, newest first (highest version first), one page at a time. Poll this after an upload or a git push to watch a build progress.
Query parameters
1.15, max 200 (larger values are clamped).Response (200 OK)
[] when there are none.Deploy fields
version_label if set, else the git commit short SHA (git), else v{version}.https://<deploy uuid>.<your plan's domain>) — independent of which version is live. Present only while preview_enabled is on and the deploy is ready/superseded.upload, git_manual, or git_push.queued → processing → ready (or failed); a replaced live version becomes superseded. Managed backends add the finer states building → image_ready → rolling_out.true is the default; false marks a candidate — a build made with activate=false (or while the app has require_manual_promotion on) that stays off production until you promote it. Use it to tell a candidate apart from a live build.true when this deploy can be activated / rolled back to / promoted — it is a terminal, built version (ready/superseded), not pruned, and not already the live version.true once the retention policy has deleted this deploy's build artifact (static bundle or OCI image). The row survives for history, but it can no longer be rolled back to. pruned_at (datetime) says when; omitted until then.pending, pass or blocked — a blocked image never rolls out) and the scan's report. Omitted for static deploys and until the scan has run.wordpress) rather than one built from your code. Omitted otherwise.status = failed — or read the full build log. Omitted otherwise.deploy_max_rollback_versions entitlement, per plan). Older deploys are pruned — their artifacts are deleted and rollbackable is false. The live version is always kept.
auto_activate lets you tell them apart: a deploy created with activate=false (a candidate) has auto_activate: false and never touched production — it just built; turn on its preview to get a preview_url. Promote it with activate when it checks out. Note that “live” only exists once the app has a production endpoint; an app with deploys but no attached endpoint just has builds.
Activate (Restart / Rollout / Rollback)
Make any built, non-current deploy the live one — promote a newer candidate, roll back to an older version, or restart the current one. There is no separate promote endpoint: it's the same call either way. For static apps this is an atomic pointer flip; for managed / fullstack apps it re-rolls the pod onto that deploy's digest-pinned image. A pruned version can't be activated (409).
See the full reference on the dedicated page: Activate (Promote / Roll back / Restart).
Redeploy
Rebuild and re-ship the application — an upload app from its last uploaded source, a git app from the latest commit of its production branch — with no re-upload or push needed. For an upload app the source of its newest deploy (highest version) is reused, a fresh deploy is created, and a build job is enqueued (a static bundle rebuild, or a signed image rebuild for managed / fullstack apps). Useful to pick up a changed environment variable, changed build settings or a base-image refresh without re-sending the archive. Every redeploy builds with the app's current build settings, and for a managed, fullstack or function app it always builds a fresh image.
For a git app it builds the head of the configured branch, like the first deploy on connect, so it works while push-to-deploy is off (auto_deploy false) and to retry a failed build.
Request (multipart/form-data, optional)
false, 0, no, off) rebuilds a candidate — it builds without disturbing production. Promote it afterward. Omit the body entirely to redeploy live as before (or as a candidate when the app has require_manual_promotion on).Response (202 Accepted)
uuid, version, status: "queued", auto_activate, …). Poll list deploys or the build log for progress.queued.