--- title: "Start a new Deployment." method: POST path: "/orgs/{orgId}/apps/{appId}/envs/{envId}/deploys" tags: ["public", "Deployment"] --- # Start a new Deployment. `POST /orgs/{orgId}/apps/{appId}/envs/{envId}/deploys` At Humanitec, Deployments are defined as changes to the state of the Environment. The state can be changed by defining a set of desired changes to the current state via a Deployment Delta or by resetting the current state after a previous Deployment. (See Environment Rebase.) Both types of changes can be combined into a single Deployment during which the Delta is applied to the Rebased state. When specifying a Delta, a Delta ID must be used. That Delta must have been committed to the Delta store prior to the Deployment. A Set ID can also be defined in the deployment to force the state of the environment to a particular state. This will be ignored if the Delta is specified. **NOTE:** Directly setting a `set_id` in a deployment is not recommended as it will not record history of where the set came from. If the intention is to replicate an existing environment, use the environment rebasing approach described above. ## Path parameters - `orgId` string, required - `appId` string, required - `envId` string, required ## Request body - DeploymentRequest — Deployments represent updates to the running state of an Environment. Deployments are made by applying _Deltas_ to a state defined by an existing Deployment. The Environment’s from_deploy property defines the Deployment. This Deployment is usually but not always in the current Environment. If the Deployment is from another Environment, the state of that Environment will be "cloned" into the current Environment with the option to apply a Delta. - `comment` string — An optional comment to help communicate the purpose of the Deployment. - `delta_id` string — ID of the Deployment Delta describing the changes to the current Environment for this Deployment. - `pipeline` DeploymentPipelineReferenceRequest - `id` string — The ID of the Pipeline - `job_id` string — The ID of the Pipeline Job within the Run. - `run_id` string — The ID of the Pipeline Run - `step_index` integer — The index of the step with in the Job. - `mode` 'full' | 'incremental' — The deployment mode. Must be "full" or "incremental". Defaults to "full" when absent. "incremental" is only valid in direct (non-legacy) mode. - `set_id` string — ID of the Deployment Set describing the state of the Environment after Deployment. - `value_set_version_id` string, nullable — ID of the Value Set Version describe the values to be used for this Deployment. ## Response `201` A description of the Deployment. - DeploymentResponse — Deployments represent updates to the running state of an Environment. Deployments are made by applying _Deltas_ to a state defined by an existing Deployment. The Environment’s from_deploy property defines the Deployment. This Deployment is usually but not always in the current Environment. If the Deployment is from another Environment, the state of that Environment will be "cloned" into the current Environment with the option to apply a Delta. - `comment` string, required — An optional comment to help communicate the purpose of the Deployment. - `created_at` string, date-time, required — The Timestamp of when the Deployment was initiated. - `created_by` string, required — The user who initiated the Deployment. - `delta_id` string — ID of the Deployment Delta describing the changes to the current Environment for this Deployment. - `env_id` string, required — The Environment where the Deployment occurred. - `export_file` string, required - `dependency_graph_id` string — The ID of the Dependency Graph which holds the sorted list of the resources provisioned with this deployment. The referenced Graph does not include resources of type k8s-cluster and k8s-namespace (and logging in case of deployments executed in Operator mode). - `legacy_mode` boolean — Defines if it's a Legacy Mode deployment, nil means either the mode is unknown or the deployment not yet finished. - `operator_version` string — The version of the Humanitec Operator that performed this Deployment. Only set in Operator Mode; nil if the version is unknown, could not be retrieved, or the Deployment has not yet finished. - `mode` string — The deployment mode. Either "full" or "incremental". "incremental" is only valid in direct (non-legacy) mode. - `export_status` string, required - `from_id` string, required — The ID of the Deployment that this Deployment was based on. - `id` string, required — The ID of the Deployment. - `pipeline` DeploymentPipelineReferenceResponse - `id` string, required — The ID of the Pipeline - `job_id` string, required — The ID of the Pipeline Job within the Run. - `run_id` string, required — The ID of the Pipeline Run - `step_index` integer, required — The index of the step with in the Job. - `set_id` string, required — ID of the Deployment Set describing the state of the Environment after Deployment. - `status` string, required — The current status of the Deployment. Can be `pending`, `in progress`, `succeeded`, or `failed`. - `status_changed_at` string, date-time, required — The timestamp of the last `status` change. If `status` is `succeeded` or `failed` it it will indicate when the Deployment finished. - `value_set_version_id` string, nullable — ID of the Value Set Version describe the values to be used for this Deployment. ## Other responses - `400` — Error because the Delta is non-existent or incompatible with the state of the Environment. - `404` — No Environment with `id` in Application. - `409` — There is already an active deployment in the Environment. --- [API](https://skmtc.net/humanitec/apis/humanitec-api.md) · [All operations](https://skmtc.net/humanitec/apis/humanitec-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/humanitec/humanitec-api/revisions/e21ad140ec3c/schema)