curl -X POST https://api.vertracloud.app/v1/apps/9d2c7e41-60fa-4b13-8e75-c1a4b3f08d26/template/update \
-H "Authorization: Bearer $VERTRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "ram": { "app": 384 } }'
{
"response": {
"id": "c8a15d73-2f90-4e6b-b7d4-0e9a6c3f1b58",
"kind": "update",
"template_id": "7c1d4f0e-3b8a-4d52-9a66-1f0c2e5a9b41",
"version_id": "e0b7a2c9-5d14-4f8e-8c3a-92d6b1f47a10",
"version": "1.1.0",
"status": "queued",
"current_step": null,
"steps": [
{ "step": "validate", "status": "pending", "started_at": null, "finished_at": null },
{ "step": "snapshot", "status": "pending", "started_at": null, "finished_at": null },
{ "step": "apps", "status": "pending", "started_at": null, "finished_at": null },
{ "step": "start", "status": "pending", "started_at": null, "finished_at": null },
{ "step": "healthcheck", "status": "pending", "started_at": null, "finished_at": null }
],
"error": null,
"resources": [],
"stack_id": null,
"application_id": "9d2c7e41-60fa-4b13-8e75-c1a4b3f08d26",
"outputs": [],
"created_at": "2026-10-29T09:00:00Z",
"updated_at": "2026-10-29T09:00:00Z",
"finished_at": null
}
}
Templates
Update a Template or Move an App to Its Latest Version
Starts an update job that moves an application or stack to the latest version of its template, takes a safety snapshot first and goes back if a step fails.
POST
/
v1
/
apps
/
{id}
/
template
/
update
curl -X POST https://api.vertracloud.app/v1/apps/9d2c7e41-60fa-4b13-8e75-c1a4b3f08d26/template/update \
-H "Authorization: Bearer $VERTRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "ram": { "app": 384 } }'
{
"response": {
"id": "c8a15d73-2f90-4e6b-b7d4-0e9a6c3f1b58",
"kind": "update",
"template_id": "7c1d4f0e-3b8a-4d52-9a66-1f0c2e5a9b41",
"version_id": "e0b7a2c9-5d14-4f8e-8c3a-92d6b1f47a10",
"version": "1.1.0",
"status": "queued",
"current_step": null,
"steps": [
{ "step": "validate", "status": "pending", "started_at": null, "finished_at": null },
{ "step": "snapshot", "status": "pending", "started_at": null, "finished_at": null },
{ "step": "apps", "status": "pending", "started_at": null, "finished_at": null },
{ "step": "start", "status": "pending", "started_at": null, "finished_at": null },
{ "step": "healthcheck", "status": "pending", "started_at": null, "finished_at": null }
],
"error": null,
"resources": [],
"stack_id": null,
"application_id": "9d2c7e41-60fa-4b13-8e75-c1a4b3f08d26",
"outputs": [],
"created_at": "2026-10-29T09:00:00Z",
"updated_at": "2026-10-29T09:00:00Z",
"finished_at": null
}
}
Moves an application or a stack to the latest version of its template, as one asynchronous operation, and answers
An empty body is valid.
The response is the template, in the same shape as Get Template. A template that is not yours answers
202 Accepted with a job of kind: "update". There are two routes with the same body and response: POST /v1/apps/{id}/template/update and POST /v1/stacks/{stack_id}/template/update. The needed scope is templates:deploy. Only the owner of the account or workspace can update; a workspace member gets WORKSPACE_OWNER_ONLY. Check what will happen first with Get Template Update Info. The update never runs by itself.
The job takes a safety snapshot, updates the services one after the other and, if any step fails, goes back to the snapshot and removes what it created, so everything returns to how it was. An application of a stack made from a template is updated together with the whole stack. The job takes the same one-deploy-at-a-time lock as Deploy Template. The steps are the ones of Get Deploy Job, plus snapshot, and rollback when a failed update goes back. Follow it with that page or the event stream. More on the behavior in Updates and rollback.
What an update changes: the code or image version of the services, the memory they need, new variables the template introduced and new services. Variables you changed, variables you deleted and your own files stay as they are. Permissions are never made more restrictive. A service the new version drops leaves the template but is not deleted. Services new in the version are created with the same steps as a deploy.
string
required
The application ID (on the
/v1/apps/{id}/template/update route).string
required
The stack ID (on the
/v1/stacks/{stack_id}/template/update route).object
Your answers to the required questions the new version adds (
new_inputs in Get Template Update Info), by question ID. Questions of the earlier version are not asked again. An invalid or missing answer fails with TEMPLATE_INPUT_INVALID.object
The new memory in MB, by service ID, for the services whose minimum memory rose (
ram_changes). A service that rises with no value here goes to the new minimum, never below it.Response
Status202 with the job in the queued status.
object
The job, with the fields described in Get Deploy Job. Here
kind is update, and stack_id or application_id point to the resource being updated.curl -X POST https://api.vertracloud.app/v1/apps/9d2c7e41-60fa-4b13-8e75-c1a4b3f08d26/template/update \
-H "Authorization: Bearer $VERTRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "ram": { "app": 384 } }'
{
"response": {
"id": "c8a15d73-2f90-4e6b-b7d4-0e9a6c3f1b58",
"kind": "update",
"template_id": "7c1d4f0e-3b8a-4d52-9a66-1f0c2e5a9b41",
"version_id": "e0b7a2c9-5d14-4f8e-8c3a-92d6b1f47a10",
"version": "1.1.0",
"status": "queued",
"current_step": null,
"steps": [
{ "step": "validate", "status": "pending", "started_at": null, "finished_at": null },
{ "step": "snapshot", "status": "pending", "started_at": null, "finished_at": null },
{ "step": "apps", "status": "pending", "started_at": null, "finished_at": null },
{ "step": "start", "status": "pending", "started_at": null, "finished_at": null },
{ "step": "healthcheck", "status": "pending", "started_at": null, "finished_at": null }
],
"error": null,
"resources": [],
"stack_id": null,
"application_id": "9d2c7e41-60fa-4b13-8e75-c1a4b3f08d26",
"outputs": [],
"created_at": "2026-10-29T09:00:00Z",
"updated_at": "2026-10-29T09:00:00Z",
"finished_at": null
}
}
Error Responses
string
The error code indicating the reason for the failure. Possible values:
VALIDATION_ERROR: The ID or the body is not valid (400).TEMPLATE_INPUT_INVALID: An answer is invalid, or a memory value is outside what the new version asks for;details.issueslists them (400).TEMPLATE_RAM_INSUFFICIENT: Not enough free memory for the new version (400).API_KEY_SCOPE_DENIED: The API key does not have thetemplates:deployscope (403).WORKSPACE_OWNER_ONLY: Only the owner of the workspace can update (403).TEMPLATE_PLAN_REQUIRED: The new version needs a plan above yours;details.reasonsays why (403).TEMPLATE_IMAGE_SLOTS_EXHAUSTED: The new version needs an image slot and none is free (403).APP_NOT_FOUND,STACK_NOT_FOUND: The application or stack does not exist or is not yours (404).TEMPLATE_NOT_FOUND: The application or stack did not come from a template (404).TEMPLATE_UPDATE_BLOCKED: The update cannot go ahead.details.reasonis one ofno_new_version,detached,template_removed,link_revokedorapp_building(409).TEMPLATE_DEPLOY_IN_PROGRESS: Another deploy or update of your account is running (409).RATE_LIMIT_EXCEEDED: Too many requests (429).INTERNAL_SERVER_ERROR: Unexpected failure (500).
202 is not returned here: the job goes back to the snapshot and ends as failed, with the code in error.code.{
"code": "TEMPLATE_UPDATE_BLOCKED",
"details": { "reason": "no_new_version" }
}
Edit a private template
PATCH https://api.vertracloud.app/v1/templates/{template_id} changes the details of one of your private templates: the name, the description, the category and the tags. It needs the templates:write scope and at least one field. A new manifest is not an edit: it is a new version, created with Create Template Version.
object
The name in each language:
pt-br, en and es (up to 50 characters each).object
The description in each language (up to 128 characters each).
string
One of the categories returned by List Template Categories.
string[]
Up to 10 tags.
TEMPLATE_NOT_FOUND (404).Last modified on October 28, 2026