App Environment Management API

The App Environment Management API allows you to manage resources, scaling, and apply pending changes to app environments in Quave ONE.

Make sure to read the Get Started document to understand how the API works.

Note: All endpoints in this API accept both appEnvId and envName parameters for identifying the environment.

Patch a JSON Environment Variable

PATCH /api/public/v1/app-env/variable/json-patch updates one field within a JSON environment variable. Provide appEnvId or envName, variableName, jsonPath, and value; set applyImmediately: true only to apply the changes immediately rather than leave them pending.

The operation requires an authenticated account admin (or the explicit internal Operator plus Security policy). MCP requests require quave:write:config and quave:read:secrets; OAuth requests must hold the endpoint's required scopes. These checks apply even when the target JSON is not marked secret.

Only the target variable is decrypted, when necessary. Unrelated variables remain unchanged and encrypted. Missing variables return 404; invalid JSON returns 400 without including its contents. Missing permissions return 403. Failures while processing authorized secrets return 500 with Unable to process environment variable secrets, not an admin-permission error.

Apply Pending Changes

Applies any pending configuration changes to an app environment. This works like terraform apply - it takes the pending changes (from resources, scaling, env vars updates, Job config updates, startup command updates, etc.) and deploys them to the infrastructure.

Endpoint: POST /api/public/v1/app-env/apply-changes

Request Body

Field	Type	Required	Description
appEnvId	String	Either	The ID of the app environment.
envName	String	Either	The CLI environment name (alternative to appEnvId).

Example

curl -X POST \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b"
    }' \
    https://api.quave.cloud/api/public/v1/app-env/apply-changes

Example Response

{
  "success": true,
  "message": "Changes applied successfully",
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production",
    "status": "UPDATING"
  }
}

Notes

• If there are no pending changes, the API will return a success response with a message indicating no changes were applied.
• The operation determines the type of changes (build, deploy, or scale) and executes them in the correct priority order.
• For Job apps, applying Job config changes updates the applied Job config snapshot used by future default JobRuns. It does not run the Job by itself.
• For regular Apps and Functions, applying a startup command change redeploys the current content with the saved runtime override. It does not rebuild the image. See Startup Command Overrides.

---

Update Resources

Updates the resource allocation for an app environment. You can use either zClouds (simplified abstraction) or custom resources (CPU/memory) for Connect accounts. Disk storage can be set for managed databases and regular app environments with a local persistent volume.

Endpoint: PATCH /api/public/v1/app-env/resources

Request Body

Field	Type	Required	Description
appEnvId	String	Either	The ID of the app environment.
envName	String	Either	The CLI environment name (alternative to appEnvId).
zClouds	Number	No	Number of zClouds. 1 zCloud includes 0.5 CPU, 512 MB memory, and 5 GB of included managed-database disk allowance.
cpu	Number	No	CPU limit in cores (e.g., 2.0). Requires a Connect account.
cpuRequest	Number	No	CPU request (guaranteed minimum). Must not exceed cpu. Requires a Connect account.
memory	Number	No	Memory limit in MB (e.g., 2048). Requires a Connect account.
memoryRequest	Number	No	Memory request (guaranteed minimum). Must not exceed memory. BYOP.
disk	Number	No	Allocated disk storage in MB. Applies only to managed databases and regular app environments with a local persistent volume (useVolume=true and useNfsVolume=false). Once this disk size has been applied, this value can only stay the same or increase. Shared NFS volumes and stateless apps do not use this disk setting. For DevOps databases, use at least 1000 MB (1 GB). Starting with July 2026 billing, eligible Direct local disk above the included zClouds * 5 GB allowance is billed as storage overage. See pricing.
networkIngress	Number	No	Network ingress in Mbps. Requires a Connect account.
networkEgress	Number	No	Network egress in Mbps. Requires a Connect account.
databaseSettings	Object	No	Managed MongoDB only: the MongoDB Search size, sent as { "mongodb": { "search": { ... } } } with enabled, resources.zClouds (1, 2, 4, or 8), replicas (1 to 3; not exposed in the console yet) and storage (MB, grow-only). Omitted fields keep their current values; any other databaseSettings key is rejected. See MongoDB Settings.
applyImmediately	Boolean	No	If true, deploy changes immediately. Default: false (pending changes).

Example: Update zClouds

curl -X PATCH \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "zClouds": 4,
        "applyImmediately": true
    }' \
    https://api.quave.cloud/api/public/v1/app-env/resources

Example: Size MongoDB Search

curl -X PATCH \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "databaseSettings": {
            "mongodb": {
                "search": { "resources": { "zClouds": 4 }, "storage": 20480 }
            }
        }
    }' \
    https://api.quave.cloud/api/public/v1/app-env/resources

Example: Update Custom Resources (Connect)

curl -X PATCH \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "cpu": 2.0,
        "cpuRequest": 1.0,
        "memory": 2048,
        "memoryRequest": 1024,
        "disk": 10240
    }' \
    https://api.quave.cloud/api/public/v1/app-env/resources

Example Response

{
  "success": true,
  "message": "Resources updated and changes applied",
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production",
    "zClouds": 4
  },
  "appliedImmediately": true
}

Notes

• zClouds vs Custom Resources: Use zClouds for simplified resource allocation, or custom fields (cpu, memory, disk) for fine-grained control. Don't mix both.
• Connect Requirement: Custom resources are only available for accounts with Quave ONE Connect enabled (legacy API fields may still use BYOP names).
• Persistent Disk: Auto-provisioned database disks must be between the minDiskMb and maxDiskMb values returned by GET /api/public/v1/database-presets; pass accountId to receive the target account's effective maximum. On the account's own node pool (a Connect private region), the maximum follows the largest data disk of the pool instead, including its data disk autogrow maximum, unless support set a per-account limit (database-presets still reports the shared maximum); a create or disk increase is also rejected when it would overcommit the node data disk, and database CPU/memory must fit one node of the pool. Regular app local persistent volumes default to 1000 MB, and support can configure a higher per-account maximum. Applied disks are grow-only: updates may keep the current value or increase it, but decreases are rejected. Redis without persistence is the database exception and uses disk: 0.
• Request vs Limit: Request values are the guaranteed minimum resources; limit values are the maximum. Request must not exceed limit. When zClouds changes, requests are compared with the limits of the new size, and an update that would leave a request above its limit is rejected with a 400 that names the request and the limit.

---

Update Storage Autoresize

Sets the disk autoresize policy of a managed database (Databases & Services) or a regular app environment with a local persistent volume. When enabled, Quave ONE grows the disk when usage crosses the trigger or free space drops below the minimum, without a redeploy. Disks never shrink. See Disk Autoresize for how it works and its cost impact.

Endpoint: PATCH /api/public/v1/app-env/storage-autoresize

Requires an account member with access to the environment (the same permission as changing disk). MCP: update-app-env-storage-autoresize with the quave:write:config scope.

Request Body

Field	Type	Required	Description
appEnvId	String	Either	The ID of the app environment.
envName	String	Either	The CLI environment name (alternative to appEnvId).
enabled	Boolean	Yes	Turn automatic growth on or off.
maxDiskMb	Number	When enabled	Largest disk autoresize may reach, in decimal MB. At least the current disk and at most the account limit.
triggerUsedPercent	Number	No	Grow when used space reaches this percent (50 to 95). Default: 80.
minFreeGb	Number	No	Also grow when free space drops below this many GB. Default: not set.
stepPercent	Number	No	Growth per grow as a percent of the current disk (5 to 100). Default: 20.
minStepGb	Number	No	Smallest growth per grow, in GB. Default: 10.
cooldownMinutes	Number	No	Minutes between two automatic grows (5 to 1440). Default: 30.
dryRun	Boolean	No	Validate and return the policy without saving it. Default: false.

Send the full policy: omitted optional fields fall back to their defaults. The last action (lastAction) is kept.

Example: Preview

curl -X PATCH \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "enabled": true,
        "maxDiskMb": 200000,
        "minFreeGb": 20,
        "dryRun": true
    }' \
    https://api.quave.cloud/api/public/v1/app-env/storage-autoresize

Example Response (dry run)

{
  "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
  "success": true,
  "dryRun": true,
  "storageAutoResize": {
    "enabled": true,
    "triggerUsedPercent": 80,
    "minFreeGb": 20,
    "stepPercent": 20,
    "minStepGb": 10,
    "maxDiskMb": 200000,
    "cooldownMinutes": 30
  },
  "previous": null,
  "currentDiskMb": 100000,
  "accountMaxDiskMb": 500000
}

Without dryRun, the policy is saved and the response is { "appEnvId", "success": true, "storageAutoResize" }.

Notes

• Grow-only: every automatic grow is permanent. Turning the policy off stops future grows and keeps the current size.
• Limits: maxDiskMb above the account limit, below the current disk, or missing while enabled is rejected with 400. Enabling it on an environment that is not deployed, or that is not a managed database or a local persistent volume, is rejected too.
• Cost: on Quave ONE Direct, each grow increases the billed disk. See persistent disk storage overage.
• Status: GET /api/public/v1/app-env returns the policy and its lastAction in storageAutoResize.

---

Update Scaling Options

Updates Autoscaling and Connect Scale to zero in one atomic configuration change. You may send either nested object or both. Autoscaling can be available to Direct accounts when enabled for the account; Scale to zero is available only to eligible Connect accounts with account Autoscaling enabled.

Omitted autoscaling fields preserve existing settings. For settings not yet configured, the API/MCP uses the same defaults as the dashboard: minimum 1, maximum 5, CPU target 70% when neither metric is configured, scale-down window 300 seconds, scale-up window 0 seconds, and increment/decrement step 1. A memory-only policy stays memory-only. Explicit zero stabilization windows remain zero. Defaults are persisted when autoscaling is enabled; disabling alone does not reset its policy. Redeploys also normalize incomplete legacy scale snapshots without substituting unapplied settings from the environment.

Endpoint: PATCH /api/public/v1/app-env/scaling-options

Request Body

Field	Type	Required	Description
appEnvId / envName	String	Either	App environment identifier.
autoscaling	Object	No	Warm container policy: autoScalingEnabled, containers (Immediate Desired), replica range, targets, steps and stabilization windows.
scaleToZero	Object	No	Idle parking policy: enabled, idleMinutes, wakeTimeoutSeconds, and wakeMode.
applyImmediately	Boolean	No	Deploy now with a user/API token; default is pending changes. Environment tokens can save the pending configuration, but cannot apply it immediately.

Example

curl -X PATCH -H 'Authorization: YOUR_TOKEN' -H 'Content-Type: application/json' \
  -d '{"appEnvId":"5f7b1b7b7b7b7b7b7b7b7b7b","autoscaling":{"autoScalingEnabled":true,"containers":2,"minReplicaCount":1,"maxReplicaCount":5,"cpuTargetUtilization":70},"scaleToZero":{"enabled":true,"idleMinutes":60,"wakeMode":"BLOCKING"},"applyImmediately":true}' \
  https://api.quave.cloud/api/public/v1/app-env/scaling-options

---

Scale Containers

Manually scales the number of containers for an app environment.

Endpoint: POST /api/public/v1/app-env/scale

Request Body

Field	Type	Required	Description
appEnvId	String	Either	The ID of the app environment.
envName	String	Either	The CLI environment name (alternative to appEnvId).
containers	Number	Yes	Number of containers to run (at least 1).
applyImmediately	Boolean	No	If true, deploy changes immediately. Default: false.

Example

curl -X POST \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "containers": 5,
        "applyImmediately": true
    }' \
    https://api.quave.cloud/api/public/v1/app-env/scale

Example Response

{
  "success": true,
  "message": "Container count updated and changes applied",
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production",
    "containers": 5
  },
  "appliedImmediately": true
}

Notes

• If autoscaling is enabled, manual scaling will temporarily override it until the next autoscaling event.
• Consider disabling autoscaling if you need consistent manual control over container count.

---

Error Responses

All endpoints may return the following error responses:

Status	Description
400	Invalid request (missing required fields, invalid values).
401	User not authenticated.
403	User doesn't have permission to access this app environment.
404	App environment not found for the given appEnvId or envName.

Secret revelation requires the account-level Secrets Access role; Admin alone does not grant it. Existing authentication, resource-access, MFA and API/MCP scope requirements still apply. See User Roles.