---
title: "Update environment settings"
method: POST
path: "/v2/environments.updateSettings"
tags: ["environments"]
---

# Update environment settings

`POST /v2/environments.updateSettings`

Update the build, runtime, and regional settings for an environment.

All settings fields are optional. Omit a field to leave it unchanged. For
nullable fields (`dockerfile`, `healthcheck`, `openapiSpecPath`), send null
to clear the value. When `regions` is present it replaces the full set of
regions for the environment.

**Required Permissions**

Your root key must have one of the following permissions:
- `environment.*.update_environment` (to update any environment)
- `environment.<environment_id>.update_environment` (to update a specific environment)

## Request body

- V2EnvironmentsUpdateSettingsRequestBody
  - `project` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `app` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `environment` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `dockerfile` string, nullable — Path to the Dockerfile used for builds. Omit to leave unchanged; set null to clear and fall back to Railpack.
  - `rootDirectory` string — The directory your app lives in. Unkey builds from here. Use "." for the repository root, or set a subdirectory when your app is nested (e.g., services/api). Omit to leave unchanged.
  - `buildCommand` string, nullable — Overrides the build command auto-detected by Railpack. Omit to leave unchanged; set null to clear and fall back to auto-detection.
  - `watchPaths` string[] — Glob paths that trigger auto-deploys when changed. Omit to leave unchanged.
  - `autoDeploy` boolean — Whether pushes auto-deploy. Omit to leave unchanged.
  - `port` integer — Container port the app listens on. Omit to leave unchanged.
  - `vCpus` number, double — CPU allocation in vCPUs. Minimum 0.25 (1/4 vCPU), in steps of 0.25. The upper bound is your workspace's per-instance quota; exceeding it returns 400. Omit to leave unchanged.
  - `memoryMib` integer — Memory allocation in MiB. Minimum 256, in steps of 256. The upper bound is your workspace's per-instance quota; exceeding it returns 400. Omit to leave unchanged.
  - `storageMib` integer — Ephemeral storage allocation in MiB, in steps of 512 (0 for none). The upper bound is your workspace's per-instance quota; exceeding it returns 400. Omit to leave unchanged.
  - `command` string[] — Override container entrypoint command. Omit to leave unchanged.
  - `healthcheck` EnvironmentHealthcheck
    - `method` 'GET' | 'POST', required — HTTP method used to probe the container.
    - `path` string, required — HTTP path probed on the container. Must start with a slash.
    - `intervalSeconds` integer — How often the probe runs, in seconds. Defaults to 10 when omitted.
    - `timeoutSeconds` integer — Per-probe timeout, in seconds. Defaults to 5 when omitted.
    - `failureThreshold` integer — Consecutive failures before the container is restarted. Defaults to 3 when omitted.
    - `initialDelaySeconds` integer — Delay before the first probe runs, in seconds. Defaults to 0 when omitted.
  - `shutdownSignal` 'SIGTERM' | 'SIGINT' | 'SIGQUIT' | 'SIGKILL' — Signal sent to the container on shutdown.
  - `upstreamProtocol` 'http1' | 'h2c' — Protocol used to reach the container.
  - `openapiSpecPath` string, nullable — Path to the OpenAPI spec file within the build. Must start with a slash. Omit to leave unchanged; set null to clear.
  - `regions` EnvironmentRegion[] — Desired set of regions with per-region replica bounds. Omit to leave regions unchanged; when present, this replaces the full set (regions absent from the list are removed). At least one region is required; an empty list is rejected because an environment cannot have zero regions.
    - `name` string, required — Region name, such as us-east-1.
    - `replicas` Replicas, required — Min and max replica bounds for autoscaling in a region.
      - `min` integer, required — Minimum number of replicas.
      - `max` integer, required — Maximum number of replicas.

## Response `200`

Successfully updated the environment settings.

- V2EnvironmentsUpdateSettingsResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` EmptyResponse, required — Empty response object by design. A successful response indicates this operation was successfully executed.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden - Insufficient permissions (requires `environment.*.update_environment`)
- `404` — Not Found - The requested environment does not exist in your workspace
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/revisions/4bd11a7252bc/schema)