> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

Moves an application or a stack to the latest version of its template, as one asynchronous operation, and 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](https://docs.vertracloud.app/api-reference/endpoint/templates/update-info.md). 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](https://docs.vertracloud.app/api-reference/endpoint/templates/deploy.md). The steps are the ones of [Get Deploy Job](https://docs.vertracloud.app/api-reference/endpoint/templates/deploy-status.md), plus `snapshot`, and `rollback` when a failed update goes back. Follow it with that page or the [event stream](https://docs.vertracloud.app/api-reference/endpoint/templates/deploy-events.md). More on the behavior in [Updates and rollback](https://docs.vertracloud.app/templates/use/updates-and-rollback.md).

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.

**id** `string` *required*

The application ID (on the `/v1/apps/{id}/template/update` route).

**stack\_id** `string` *required*

The stack ID (on the `/v1/stacks/{stack_id}/template/update` route).

**inputs** `object`

Your answers to the required questions the new version adds (`new_inputs` in [Get Template Update Info](https://docs.vertracloud.app/api-reference/endpoint/templates/update-info.md)), by question ID. Questions of the earlier version are not asked again. An invalid or missing answer fails with `TEMPLATE_INPUT_INVALID`.

**ram** `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.

An empty body is valid.

### Response

Status `202` with the job in the `queued` status.

**response** `object`

The job, with the fields described in [Get Deploy Job](https://docs.vertracloud.app/api-reference/endpoint/templates/deploy-status.md). Here `kind` is `update`, and `stack_id` or `application_id` point to the resource being updated.

```bash cURL theme={null}
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 } }'
```

```json Response theme={null}
{
  "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

**code** `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.issues` lists them (`400`).
* `TEMPLATE_RAM_INSUFFICIENT`: Not enough free memory for the new version (`400`).
* `API_KEY_SCOPE_DENIED`: The API key does not have the `templates:deploy` scope (`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.reason` says 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.reason` is one of `no_new_version`, `detached`, `template_removed`, `link_revoked` or `app_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`).

A failure after the `202` is not returned here: the job goes back to the snapshot and ends as `failed`, with the code in `error.code`.

```json Error Response theme={null}
{
  "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](https://docs.vertracloud.app/api-reference/endpoint/templates/new-version.md).

**name** `object`

The name in each language: `pt-br`, `en` and `es` (up to 50 characters each).

**description** `object`

The description in each language (up to 128 characters each).

**category** `string`

One of the categories returned by [List Template Categories](https://docs.vertracloud.app/api-reference/endpoint/templates/categories.md).

**tags** `string[]`

Up to 10 tags.

The response is the template, in the same shape as [Get Template](https://docs.vertracloud.app/api-reference/endpoint/templates/get.md). A template that is not yours answers `TEMPLATE_NOT_FOUND` (`404`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.