--- title: "Add a new Environment to an Application." method: POST path: "/orgs/{orgId}/apps/{appId}/envs" tags: ["public", "Environment"] --- # Add a new Environment to an Application. `POST /orgs/{orgId}/apps/{appId}/envs` Creates a new Environment of the specified Type and associates it with the Application specified by `appId`. The Environment is also initialized to the **current or past state of Deployment in another Environment**. This ensures that every Environment is derived from a previously known state. This means it is not possible to create a new Environment for an Application until at least one Deployment has occurred. (The Deployment does not have to be successful.) The Type of the Environment must be already defined in the Organization. ## Path parameters - `orgId` string, required - `appId` string, required ## Request body - EnvironmentDefinitionRequest - `from_deploy_id` string — Defines the existing Deployment the new Environment will be based on. - `id` string, required — The ID the Environment is referenced as. - `name` string, required — The Human-friendly name for the Environment. - `type` string — The Environment Type. This is used for organizing and managing Environments. ## Response `201` The new Environment. - EnvironmentResponse — Environments are independent spaces where Applications can run. An Application is always deployed into an Environment. - `created_at` string, date-time, required — The timestamp in UTC of when the Environment was created. - `created_by` string, required — The user who created the Environment - `from_deploy` 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. - `id` string, required — The ID the Environment is referenced as. - `last_deploy` 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. - `name` string, required — The Human-friendly name for the Environment. - `type` string, required — The Environment Type. This is used for organizing and managing Environments. - `status` 'active' | 'deleting', required — The status of the environment - `status_changed_at` string, date-time, required — The timestamp in UTC of when the Environment status was last changed. - `status_message` string — The message associated with the status of the environment ## Other responses - `400` — The supplied `id` is an invalid ID or a required field is missing. - `404` — No Application with `id` in Organization. - `409` — The supplied `id` clashes with an existing 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)