UNunkeyed
environments

Update environment settings

Changed on

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

  • Base URL
    https://api.unkey.com
  • URL
    https://api.unkey.com/v2/environments.updateSettings
  • Auth
    HTTP bearer

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 patterns that trigger auto-deploys when matching files change. Do not start a pattern with "/" or "./". Use "src/" for everything under a directory and "/*.go" for a file type. A pattern with no wildcard matches only that exact file, so "src" is not "src/**". Omit to leave unchanged. Invalid patterns are rejected with a 400.

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"
  }
}

Changes

  • 43ad1ce9a152Revision changes
    • info

      the endpoint scheme security bearer was added to the API

    • info

      the endpoint scheme security rootKey was removed from the API

  • de7b05f5cb37Revision changes
    • warning

      removed the request property

    • info

      added the new optional request property