# Preview template upgrade

`GET https://api.instacloud.com/template-deployments/{deploymentId}/upgrade`

**Token scope:** `account` · `org` · `project` — read-only tokens allowed.

What upgrading this deployment to the version the registry serves now would do: per-service field changes, which of them the upgrade writes and which it only reports, required variables with no value yet, and anything that makes the upgrade impossible. Each field row carries the label to show for it — render that label as given, because it is where a change states how far it reaches (public access on a storage service applies to that bucket on every branch). Reads only.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `deploymentId` | path | `string` | yes |  |

## Response 200

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `plan` | `object` | yes |  |
| `plan.from_version` | `string` | yes | the version this instance was deployed from |
| `plan.to_version` | `string` | yes | the version the registry serves now |
| `plan.to_digest` | `string` | yes | content digest of the manifest this plan was computed from, send it back as expected_digest so the apply cannot run a version nobody reviewed |
| `plan.services` | `object[]` | yes |  |
| `plan.services.key` | `string` | yes | the manifest key; stable across copies, where the platform name may be <key>-2 |
| `plan.services.service_id` | `string \| null` | no |  |
| `plan.services.service_name` | `string \| null` | no |  |
| `plan.services.gone` | `boolean` | yes | the deployment created it and the branch no longer has it: the user deleted it. Reported, never recreated |
| `plan.services.added` | `boolean` | yes | the new version introduces it; the upgrade creates it |
| `plan.services.fields` | `object[]` | yes | what the upgrade will write on this service. On an `added` service these are the values it will be CREATED with, so `deployed` and `live` are null and `drifted` is false; a field the manifest does not declare gets no row and takes the platform default |
| `plan.services.fields.field` | `string` | yes | the `services` column this concerns — image, port, start_command, always_on, public, volume_gib (the new version adds a volume; it is attached at this plan's size) or volume_mount_path — so a client can deep-link to the setting |
| `plan.services.fields.label` | `string` | yes | what to show for this row. Render it as given: it is where a field states how far its change reaches, e.g. public access on a storage bucket applies to that bucket on every branch |
| `plan.services.fields.deployed` | `string \| null` | no |  |
| `plan.services.fields.live` | `string \| null` | no |  |
| `plan.services.fields.next` | `string \| null` | no |  |
| `plan.services.fields.drifted` | `boolean` | yes | the live value differs from what the deployment recorded: the user changed it after deploying |
| `plan.services.fields.verdict` | `"applied" \| "refused"` | yes | applied: the upgrade writes it, which covers everything a manifest can declare for a service it keeps and for one it creates. refused: it cannot be changed in place at all, and refuses the whole upgrade |
| `plan.services.missing_variables` | `string[]` | yes |  |
| `plan.removed` | `string[]` | yes |  |
| `plan.refusals` | `string[]` | yes |  |

## Response 404

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | `string` | yes |  |

## Response 409

code template_not_served: the registry no longer serves this template. code template_up_to_date: the instance already runs the content the registry publishes. code template_superseded: this instance already moved off this deployment — the message names the one to act on instead

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | `string` | yes |  |
| `code` | `string` | no | stable machine-readable reason, e.g. private_lane_disabled, private_lane_unavailable_in_region, public_access_closed, credential_change_in_progress |