> ## Documentation Index > Fetch the complete documentation index at: https://docs.instacloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Upgrade template deployment > **Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET). Move a deployed template instance to the version the registry serves now (async — poll GET /template-deployments/:id). The SAME services are reused: image, port, start command, always-on, public access, the volume mount path and the variables are all rewritten from the new manifest, a service the new version adds is created, and a service it drops is left running. A volume the new version adds to an existing service is attached at this plan's size and mounted by the run's own deploy; an existing volume is never resized, because a manifest cannot declare a size. Public access on a STORAGE service is lineage-wide — it sets that bucket public on every branch that has a copy, not only this one, and the preview's row for the field says so. Send expectedVersion/expectedDigest from the preview so a republish between review and apply is refused rather than run. ## OpenAPI ````yaml /openapi/project.json post /projects/{projectId}/template-deployments/{deploymentId}/upgrade openapi: 3.1.0 info: title: InstaCloud API — Project level version: 0.1.0 description: >- Endpoints under `/projects/{projectId}`: branches, services, deploys, secrets, databases, storage, cron, observability, governance. Callable with any token whose binding covers the project. Generated from the platform's own OpenAPI document (https://api.instacloud.com/openapi.json); see the [API overview](/reference/api/overview) for authentication and token scopes. servers: - url: https://api.instacloud.com description: InstaCloud security: - bearerAuth: [] tags: - name: Projects description: Projects inside an organization. - name: Branches description: >- Branch environments of a project: isolated database, storage and compute per branch. - name: Services description: 'Services on a branch: compute, postgres, storage and managed databases.' - name: Deploy description: Deploy an image or a source to a compute service. - name: Compute description: Build output of a compute service. - name: Secrets description: User secrets, service credentials and how they bind into compute env. - name: Database description: Postgres databases, extensions, credentials and ad-hoc SQL. - name: Storage description: Objects in a storage service. - name: Backups description: Database backups and restores. - name: Cron description: Scheduled HTTP calls against a service or an external URL. - name: Observability description: Logs, metrics, deploy events and database insight. - name: Governance description: Per-project agent policy and the approval queue. - name: Audit description: The project's event timeline, including agent-ingested events. - name: Domains description: >- Domains bought through InstaCloud, bring-your-own zones and their DNS records. - name: Billing description: Usage, cycles, invoices and credits. - name: Templates description: Deploy a template into a project. paths: /projects/{projectId}/template-deployments/{deploymentId}/upgrade: post: tags: - Templates summary: Upgrade template deployment description: >- **Token scope:** `account` · `org` · `project` — read-only tokens refused (not a GET). Move a deployed template instance to the version the registry serves now (async — poll GET /template-deployments/:id). The SAME services are reused: image, port, start command, always-on, public access, the volume mount path and the variables are all rewritten from the new manifest, a service the new version adds is created, and a service it drops is left running. A volume the new version adds to an existing service is attached at this plan's size and mounted by the run's own deploy; an existing volume is never resized, because a manifest cannot declare a size. Public access on a STORAGE service is lineage-wide — it sets that bucket public on every branch that has a copy, not only this one, and the preview's row for the field says so. Send expectedVersion/expectedDigest from the preview so a republish between review and apply is refused rather than run. operationId: upgradeTemplateDeployment parameters: - schema: format: uuid type: string in: path name: projectId required: true - schema: format: uuid type: string in: path name: deploymentId required: true requestBody: required: true content: application/json: schema: type: object properties: variables: description: >- values for required variables the new version adds; existing values are recovered and need not be resent type: object additionalProperties: type: string expectedVersion: description: >- the version the caller reviewed; a different one in the registry answers 409 template_version_changed type: string expectedDigest: description: >- the to_digest from the preview; a different one answers 409 template_version_changed type: string responses: '202': description: Default Response content: application/json: schema: type: object properties: deploymentId: format: uuid type: string deployment: $ref: '#/components/schemas/TemplateDeployment' status: type: string enum: - approval_required approvalId: format: uuid type: string action: type: string actions: type: array items: type: string message: type: string url: type: string nextActions: type: array items: $ref: '#/components/schemas/NextAction' '400': description: Default Response content: application/json: schema: type: object properties: error: type: string missing: type: array items: type: object properties: name: type: string key: type: string description: type: string required: - name - key required: - error '403': description: Default Response content: application/json: schema: type: object properties: error: type: string required: - error '404': description: Default Response content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- code template_version_changed: republished since the review. code template_up_to_date: already running this content. code template_not_served: off the catalog. code template_no_services: the deployment owns nothing to upgrade. code template_superseded: this instance already moved off this deployment — the message names the one to act on instead content: application/json: schema: $ref: '#/components/schemas/CodedError' components: schemas: TemplateDeployment: description: One server-side template deployment run and its progress. type: object properties: id: format: uuid type: string status: description: >- partial = some services came up healthy, others failed — created resources are kept either way type: string enum: - running - succeeded - failed - partial step: description: the pipeline step the run is currently on (or stopped at) type: string enum: - create_services - write_variables - deploy - health_check templateCode: type: string templateVersion: type: string projectId: format: uuid type: string branchId: format: uuid type: string region: description: >- InstaCloud region slug every service of this deployment was created in. Deployments recorded before regions were recorded read as the platform default. type: string services: type: array items: type: object properties: name: description: >- the service's actual name on the branch, which is the manifest's name only for the first copy — a second deployment of the same template into the same branch names its services -2 and leaves the first copy alone type: string serviceId: format: uuid type: string url: type: string state: type: string enum: - pending - created - deployed - healthy - failed skipped: description: >- an upgrade stepped over this service because the user had deleted it — the run never touched it, serviceId points at the deleted row, and state stays pending however the deployment ends. Not "still in progress" type: boolean error: type: string logsTail: description: container log tail captured when a service never became healthy type: string rollbackTo: description: >- the version one step back, present only when this deployment was produced by an upgrade: what POST .../rollback would return the instance to. Absent on a first deploy, once the predecessor is gone, and on a deployment a ROLLBACK produced — that row's step back is the newer version it just left, which is offered as the update, not as a way back. Present is not a promise it will succeed — a version whose manifest is no longer recorded, or was republished with different content, still refuses at click time type: object properties: version: type: string required: - version createdAt: format: date-time type: string NextAction: type: object properties: op: description: >- Neutral logical action id, e.g. "service.add" — NOT an operationId or a CLI/MCP tool name; each client maps it to its own surface. type: string reason: description: Natural-language, human/LLM-facing "why do this now". type: string args: description: >- Suggested, flat named arguments; ""s where a value is unknown. type: object additionalProperties: true gated: description: True if the action passes a governance gate. type: boolean required: - op - reason Error: type: object properties: error: type: string required: - error CodedError: type: object properties: error: type: string code: description: >- stable machine-readable reason, e.g. private_lane_disabled, private_lane_unavailable_in_region, public_access_closed, credential_change_in_progress type: string required: - error securitySchemes: bearerAuth: type: http scheme: bearer description: Session access JWT or an API token (`insta__`). ````