Sign in

v66

OpenAPI 3.1.0raw.githubusercontent.com2026-08-0174265626.3 KB
environments

Update environment settings

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)
post/v2/environments.updateSettings

Request body

projectstring required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

appstring required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

environmentstring required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

dockerfilestring nullable

Path to the Dockerfile used for builds. Omit to leave unchanged; set null to clear and fall back to Railpack.

rootDirectorystring

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.

buildCommandstring nullable

Overrides the build command auto-detected by Railpack. Omit to leave unchanged; set null to clear and fall back to auto-detection.

watchPathsstring[]

Glob paths that trigger auto-deploys when changed. Omit to leave unchanged.

autoDeployboolean

Whether pushes auto-deploy. Omit to leave unchanged.

portinteger

Container port the app listens on. Omit to leave unchanged.

vCpusnumber 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.

memoryMibinteger

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.

storageMibinteger

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.

commandstring[]

Override container entrypoint command. Omit to leave unchanged.

shutdownSignal'SIGTERM' | 'SIGINT' | 'SIGQUIT' | 'SIGKILL'

Signal sent to the container on shutdown.

upstreamProtocol'http1' | 'h2c'

Protocol used to reach the container.

openapiSpecPathstring nullable

Path to the OpenAPI spec file within the build. Must start with a slash. Omit to leave unchanged; set null to clear.

Example request

{
  "project": "proj_1234abcd",
  "app": "proj_1234abcd",
  "environment": "proj_1234abcd",
  "dockerfile": "./Dockerfile",
  "rootDirectory": ".",
  "buildCommand": "pnpm --filter api build",
  "autoDeploy": true,
  "port": 8080,
  "vCpus": 1,
  "memoryMib": 512,
  "storageMib": 1024,
  "healthcheck": {
    "method": "GET",
    "path": "/healthz",
    "intervalSeconds": 10,
    "timeoutSeconds": 2,
    "failureThreshold": 3,
    "initialDelaySeconds": 5
  },
  "shutdownSignal": "SIGTERM",
  "upstreamProtocol": "http1",
  "openapiSpecPath": "/openapi.yaml",
  "regions": [
    {
      "name": "us-east-1",
      "replicas": {
        "min": 1,
        "max": 3
      }
    }
  ]
}

Response

Successfully updated the environment settings.

dataEmptyResponse required

Empty response object by design. A successful response indicates this operation was successfully executed.

Example response

{
  "meta": {
    "requestId": "req_123"
  }
}