---
title: "Create app version"
method: POST
path: "/apps/{name}/versions"
---

# Create app version

`POST /apps/{name}/versions`

## Request

- Base URL: `https://api.tower.dev/v1`
- URL: `https://api.tower.dev/v1/apps/{name}/versions`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/tower/apis/tower-api/docs/apps/:name/versions/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new version of an app from an existing version's code, without uploading a new package. The new version reuses the source version's code bundle and Towerfile, and can override per-version settings such as the run size and parameters. Like a deploy, the new version is then deployed to the target environment(s).

## Path parameters

- `name` string, required: The name of the app to create a version for.

## Query parameters

- `environment` string: The environment to deploy the new version to.
- `all_environments` boolean: Whether to deploy the new version to all environments for this app. If true, the 'environment' query parameter is ignored.

## Headers

- `X-Tower-Idempotency-Key` string: Optional opaque key that makes this request safe to retry: if a version of this app already has the key and the same code bundle, run size and parameters, that version is reused (and deployed to the target environments). Reusing a key with different code or settings returns 409 Conflict. When omitted, the server derives a key from the code bundle, run size and parameters, so repeating an identical request also reuses the existing version.
- `X-Tower-Request-Number` integer: Optional account-scoped monotonic sequence token used to reject out-of-order writes. See the fence documentation for the acceptance window and retry behavior.

## Request body

- CreateAppVersionBody
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `parameters` CreateAppVersionParameter[]: The parameters for the new version. Replaces the source version's full parameter list when supplied; omit to keep it, or pass an empty list to clear it.
    - `default` string: The default value of the parameter. Hidden parameters cannot have a default.
    - `description` string: A description of the parameter.
    - `hidden` boolean: Whether this parameter is hidden/secret. Defaults to false.
    - `name` string, required: The name of the parameter.
  - `run_size` string: The resource profile for the new version. Omit to keep the source version's run size; an empty string means undeclared (runs use basic.medium).
  - `source_version` string: The version whose code the new version reuses, e.g. 'v3'. Defaults to the version currently deployed to the target environment ('default' when deploying to all environments).

## Response `201`

Created

- CreateAppVersionResponse
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `version` AppVersion, required
    - `content_checksum` string: Server-computed SHA256 of the bundle contents for this version.
    - `created_at` string, date-time, required
    - `idempotency_key` string: Key that produced this version: the client-supplied key (e.g. git SHA), a server-derived key for versions created from another version's code, or empty if none was supplied at deploy time.
    - `parameters` Parameter[], required
      - `default` string, required
      - `description` string, required
      - `hidden` boolean: Whether this parameter is hidden/secret. Defaults to false.
      - `name` string, required
    - `run_size` string, required: The resource profile for this version, or empty if none was declared (runs then use basic.medium).
    - `towerfile` string, required: The Towerfile packaged with this version's code. Versions created from another version reuse its Towerfile, so run_size and parameters on the version take precedence over it.
    - `version` string, required

## Other responses

- `404`: Not Found
- `409`: Conflict
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-10-06** `d4eb8af936b9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tower/apis/tower-api/changes/apps/:name/versions/post.md)

---

[API](https://skmtc.dev/tower/apis/tower-api.md) - [All operations](https://skmtc.dev/tower/apis/tower-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tower/apis/tower-api/revisions/ad773b776902?raw)