Activate (Restart / Rollout / Rollback)
Make a built deploy the live version. Activating the current deploy is a restart / rollout (re-ship the running version); activating an older built deploy is a rollback. The build worker auto-activates the first successful deploy, so you only call this to switch versions afterward.
Only a deploy that has already been built can be activated — its status must be ready, superseded, or (managed apps) image_ready. A queued / processing / building / failed deploy is rejected with 409.
What happens depends on the app type
- Static apps — the edge serves the current deploy's built bundle directly, so activation is an atomic pointer flip (plus an edge pre-warm). No rebuild, no downtime. The response returns
{ "status": "ok", "current_deploy_id": … }and older deploys are markedsuperseded. - Managed / fullstack apps — the running pod is whatever the runtime last reconciled, so activation re-enqueues the deploy as
image_ready. The worker re-points the Deployment at that deploy's already scanned + signed, digest-pinned image, re-materializes env vars, and advances the live version only on a proven-ready rollout. The response returns{ "status": "rolling_out", "deploy_id": … }. Rollback is instant because the image is immutable and digest-pinned.
Pruned versions can't be rolled back to. Retention keeps only the newest N terminal deploys rollbackable (
deploy_max_rollback_versions). Once a deploy's build artifact is pruned (its static bundle or OCI image is deleted), activating it returns 409 — re-deploy from source instead. Check the rollbackable / pruned fields on the deploy list before offering a rollback.
Response (200 OK)
status string
ok (static) or rolling_out (managed / fullstack).current_deploy_id int64
Static apps: the now-live deploy.
deploy_id int64
Managed / fullstack apps: the deploy now rolling out (the live version advances once the rollout is proven ready).
Errors
404
Deploy not found or belongs to another application.
409
The deploy has no built image / bundle to activate (still building or failed), or its build artifacts were pruned by the retention policy and it can no longer be rolled back to.
Request — roll back / restart
curl -X POST \
"https://api.ngris.com/v1/applications/a1b2c3d4-…/deploys/c2d3e4…/activate" \
-H "X-API-KEY: <your_api_key>"
Response — 200 OK (static)
{ "status": "ok", "current_deploy_id": 455 }
Response — 200 OK (managed / fullstack)
{ "status": "rolling_out", "deploy_id": 455 }
Response — 409 (pruned version)
{
"error": "This version's build artifacts were pruned by the retention policy (keeps the newest N versions); it can no longer be rolled back to. Re-deploy from source."
}