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

environments.updateSettings

Python (SDK)

from unkey.py import Unkey, models


with Unkey(
    root_key="<YOUR_BEARER_TOKEN_HERE>",
) as unkey:

    res = unkey.environments.update_settings(project="payments", app="payments-api", environment="production", dockerfile="./Dockerfile", root_directory=".", build_command="pnpm --filter api build", auto_deploy=True, port=8080, v_cpus=1, memory_mib=512, storage_mib=1024, healthcheck={
        "method": models.EnvironmentHealthcheckMethod.GET,
        "path": "/healthz",
        "interval_seconds": 10,
        "timeout_seconds": 2,
        "failure_threshold": 3,
        "initial_delay_seconds": 5,
    }, shutdown_signal=models.EnvironmentShutdownSignal.SIGTERM, upstream_protocol=models.EnvironmentUpstreamProtocol.HTTP1, openapi_spec_path="/openapi.yaml", regions=[
        {
            "name": "us-east-1",
            "replicas": {
                "min": 1,
                "max": 3,
            },
        },
    ])

    # Handle response
    print(res)

import { Unkey } from "@unkey/api";

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.environments.updateSettings({
    project: "payments",
    app: "payments-api",
    environment: "production",
    regions: [
      {
        name: "us-east-1",
        replicas: {
          min: 1,
          max: 3,
        },
      },
    ],
  });

  console.log(result);
}

run();

package main

import(
	"context"
	"os"
	unkey "github.com/unkeyed/sdks/api/go/v2"
	"github.com/unkeyed/sdks/api/go/v2/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := unkey.New(
        unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
    )

    res, err := s.Environments.UpdateSettings(ctx, components.V2EnvironmentsUpdateSettingsRequestBody{
        Project: "payments",
        App: "payments-api",
        Environment: "production",
        Regions: []components.EnvironmentRegion{
            components.EnvironmentRegion{
                Name: "us-east-1",
                Replicas: components.Replicas{
                    Min: 1,
                    Max: 3,
                },
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2EnvironmentsUpdateSettingsResponseBody != nil {
        // handle response
    }
}

curl --request POST \
  --url https://api.unkey.com/v2/environments.updateSettings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "app": "payments-api",
  "environment": "production",
  "project": "payments",
  "regions": [
    {
      "name": "us-east-1",
      "replicas": {
        "max": 3,
        "min": 1
      }
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    app: 'payments-api',
    environment: 'production',
    project: 'payments',
    regions: [{name: 'us-east-1', replicas: {max: 3, min: 1}}]
  })
};

fetch('https://api.unkey.com/v2/environments.updateSettings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unkey.com/v2/environments.updateSettings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'app' => 'payments-api',
    'environment' => 'production',
    'project' => 'payments',
    'regions' => [
        [
                'name' => 'us-east-1',
                'replicas' => [
                                'max' => 3,
                                'min' => 1
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.unkey.com/v2/environments.updateSettings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"app\": \"payments-api\",\n  \"environment\": \"production\",\n  \"project\": \"payments\",\n  \"regions\": [\n    {\n      \"name\": \"us-east-1\",\n      \"replicas\": {\n        \"max\": 3,\n        \"min\": 1\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unkey.com/v2/environments.updateSettings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"app\": \"payments-api\",\n  \"environment\": \"production\",\n  \"project\": \"payments\",\n  \"regions\": [\n    {\n      \"name\": \"us-east-1\",\n      \"replicas\": {\n        \"max\": 3,\n        \"min\": 1\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "data": {},
  "meta": {
    "requestId": "req_1234abcd"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found",
    "errors": [
      {
        "location": "body.permissions[0].name",
        "message": "Must be at least 3 characters long",
        "fix": "Ensure the name uses only alphanumeric characters, underscores, and hyphens"
      }
    ]
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "error": {
    "detail": "Your root key requires the 'environment.*.update_environment' permission to perform this operation",
    "status": 403,
    "title": "Forbidden",
    "type": "forbidden"
  },
  "meta": {
    "requestId": "req_1234abcd"
  }
}

{
  "error": {
    "detail": "The requested environment does not exist.",
    "status": 404,
    "title": "Not Found",
    "type": "not-found"
  },
  "meta": {
    "requestId": "req_1234abcd"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

Authorizations

Authorization

string

header

required

Unkey uses bearer tokens for authentication. Public integrations use root keys, while the dashboard proxy uses short-lived JWTs. To authenticate, include the token in the Authorization header of each request:

Authorization: Bearer unkey_123

Root keys have specific permissions attached to them, controlling what operations they can perform. Legacy permissions use tuple strings like api.*.create_key; resource permissions use Unkey Resource Names plus actions, like unkey:v1:ws_123:keyspaces/*#create_key. Security best practices:

Keep root keys secure and never expose them in client-side code
Use different root keys for different environments
Rotate keys periodically, especially after team member departures
Create keys with minimal necessary permissions following least privilege principle
Monitor key usage with audit logs.

Body

application/json

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.

Required string length: 3 - 255

Pattern: ^[a-zA-Z0-9_-]+$

Example:

"proj_1234abcd"

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.

Required string length: 3 - 255

Pattern: ^[a-zA-Z0-9_-]+$

Example:

"proj_1234abcd"

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.

Required string length: 3 - 255

Pattern: ^[a-zA-Z0-9_-]+$

Example:

"proj_1234abcd"

dockerfile

string | null

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

Required string length: 1 - 500

Example:

"./Dockerfile"

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.

Required string length: 1 - 500

Example:

"."

buildCommand

string | null

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

Required string length: 1 - 1000

Example:

"pnpm --filter api build"

watchPaths

string[]

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

Maximum array length: 10

Maximum string length: 500

autoDeploy

boolean

Whether pushes auto-deploy. Omit to leave unchanged.

Example:

true

port

integer

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

Required range: 1 <= x <= 65535

Example:

8080

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.

Required range: x >= 0.25Must be a multiple of 0.25

Example:

1

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.

Required range: x >= 256Must be a multiple of 256

Example:

512

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.

Required range: x >= 0Must be a multiple of 512

Example:

1024

command

string[]

Override container entrypoint command. Omit to leave unchanged.

Maximum array length: 10

Maximum string length: 4096

healthcheck

object | null

HTTP healthcheck configuration. Omit to leave unchanged; set null to remove.

Show child attributes

shutdownSignal

enum<string>

Signal sent to the container on shutdown. Omit to leave unchanged.

Available options:

SIGTERM,

SIGINT,

SIGQUIT,

SIGKILL

Example:

"SIGTERM"

upstreamProtocol

enum<string>

Protocol used to reach the upstream container. Omit to leave unchanged.

Available options:

http1,

h2c

Example:

"http1"

openapiSpecPath

string | null

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

Required string length: 1 - 512

Pattern: ^(/[\w\-]+)+(\.[\w]+)?$

Example:

"/openapi.yaml"

regions

object[]

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.

Required array length: 1 - 5 elements

Show child attributes

Response

Successfully updated the environment settings.

meta

object

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.

Show child attributes

data

object

required

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

Last modified on July 22, 2026

List policiesRetrieve an environment's gateway policies in evaluation order: the gateway evaluates them top to bottom and the first rejection short-circuits the request. The full policy list is returned in a single response. **Required Permissions** Your root key must have one of the following permissions: - `environment.*.read_policies` (for any environment) - `environment.<environment_id>.read_policies` (for a specific environment)

⌘I

Python (SDK)

from unkey.py import Unkey, models


with Unkey(
    root_key="<YOUR_BEARER_TOKEN_HERE>",
) as unkey:

    res = unkey.environments.update_settings(project="payments", app="payments-api", environment="production", dockerfile="./Dockerfile", root_directory=".", build_command="pnpm --filter api build", auto_deploy=True, port=8080, v_cpus=1, memory_mib=512, storage_mib=1024, healthcheck={
        "method": models.EnvironmentHealthcheckMethod.GET,
        "path": "/healthz",
        "interval_seconds": 10,
        "timeout_seconds": 2,
        "failure_threshold": 3,
        "initial_delay_seconds": 5,
    }, shutdown_signal=models.EnvironmentShutdownSignal.SIGTERM, upstream_protocol=models.EnvironmentUpstreamProtocol.HTTP1, openapi_spec_path="/openapi.yaml", regions=[
        {
            "name": "us-east-1",
            "replicas": {
                "min": 1,
                "max": 3,
            },
        },
    ])

    # Handle response
    print(res)

import { Unkey } from "@unkey/api";

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.environments.updateSettings({
    project: "payments",
    app: "payments-api",
    environment: "production",
    regions: [
      {
        name: "us-east-1",
        replicas: {
          min: 1,
          max: 3,
        },
      },
    ],
  });

  console.log(result);
}

run();

package main

import(
	"context"
	"os"
	unkey "github.com/unkeyed/sdks/api/go/v2"
	"github.com/unkeyed/sdks/api/go/v2/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := unkey.New(
        unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
    )

    res, err := s.Environments.UpdateSettings(ctx, components.V2EnvironmentsUpdateSettingsRequestBody{
        Project: "payments",
        App: "payments-api",
        Environment: "production",
        Regions: []components.EnvironmentRegion{
            components.EnvironmentRegion{
                Name: "us-east-1",
                Replicas: components.Replicas{
                    Min: 1,
                    Max: 3,
                },
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2EnvironmentsUpdateSettingsResponseBody != nil {
        // handle response
    }
}

curl --request POST \
  --url https://api.unkey.com/v2/environments.updateSettings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "app": "payments-api",
  "environment": "production",
  "project": "payments",
  "regions": [
    {
      "name": "us-east-1",
      "replicas": {
        "max": 3,
        "min": 1
      }
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    app: 'payments-api',
    environment: 'production',
    project: 'payments',
    regions: [{name: 'us-east-1', replicas: {max: 3, min: 1}}]
  })
};

fetch('https://api.unkey.com/v2/environments.updateSettings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unkey.com/v2/environments.updateSettings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'app' => 'payments-api',
    'environment' => 'production',
    'project' => 'payments',
    'regions' => [
        [
                'name' => 'us-east-1',
                'replicas' => [
                                'max' => 3,
                                'min' => 1
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.unkey.com/v2/environments.updateSettings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"app\": \"payments-api\",\n  \"environment\": \"production\",\n  \"project\": \"payments\",\n  \"regions\": [\n    {\n      \"name\": \"us-east-1\",\n      \"replicas\": {\n        \"max\": 3,\n        \"min\": 1\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unkey.com/v2/environments.updateSettings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"app\": \"payments-api\",\n  \"environment\": \"production\",\n  \"project\": \"payments\",\n  \"regions\": [\n    {\n      \"name\": \"us-east-1\",\n      \"replicas\": {\n        \"max\": 3,\n        \"min\": 1\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "data": {},
  "meta": {
    "requestId": "req_1234abcd"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found",
    "errors": [
      {
        "location": "body.permissions[0].name",
        "message": "Must be at least 3 characters long",
        "fix": "Ensure the name uses only alphanumeric characters, underscores, and hyphens"
      }
    ]
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "error": {
    "detail": "Your root key requires the 'environment.*.update_environment' permission to perform this operation",
    "status": 403,
    "title": "Forbidden",
    "type": "forbidden"
  },
  "meta": {
    "requestId": "req_1234abcd"
  }
}

{
  "error": {
    "detail": "The requested environment does not exist.",
    "status": 404,
    "title": "Not Found",
    "type": "not-found"
  },
  "meta": {
    "requestId": "req_1234abcd"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}