App Environments API

The App Environments API allows you to manage app environments in Quave ONE. You can create, retrieve, and delete app environments.

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

Note: Most endpoints in this API accept only the user token. Endpoints that support environment-token authentication say so explicitly.

Create App Environment

To create a new app environment, send a POST request to the /api/public/v1/app-env endpoint. Below are the required fields:

Field	Type	Description
`accountId`	String	The ID of the account.
`appId`	String	The ID of the app.
`name`	String	The name of the app environment.
`region`	String	The region for the app environment (must be one of the allowed values).

Optional fields:

Field	Type	Description
`branch`	String	The Git branch to use. Required for apps that use GitHub.
`zClouds`	Number	The number of zClouds to use (1, 2, 4, or 8). Defaults to 1.
`envVars`	Array	The environment variables to set in the app environment. See Environment Variables Object for more details.
`dockerPresetVersion`	String	The Docker preset version to use when creating a managed database environment. Call `GET /api/public/v1/database-presets` first to discover versions for MONGODB, POSTGRESQL, MYSQL, REDIS, COUCHDB, RABBITMQ, and CLICKHOUSE.
`containers`	Integer	The number of containers for managed database environments. CouchDB currently supports exactly `1`.
`disk`	Integer	Disk size in MB for managed database environments and regular apps with a local persistent volume. Starting with July 2026 billing, eligible Direct local disk above the included `zClouds * 5 GB` allowance is billed as storage overage. See pricing.
`withPersistence`	Boolean	Whether the managed database environment should use persistent storage.
`databaseSettings`	Object	Database engine settings. See Database Settings Object for more details.
`jobConfig`	Object	Job environment overrides such as command, timeout, TTL, retry, and concurrency. Only for Job apps. These values become the initial saved settings for the environment; see Job Runs API.
`startupConfig`	Object	Initial persistent startup command override for regular Apps and Functions. Not supported for Jobs or Databases & Services. See Startup Config Object.
`replaceStartupConfig`	Boolean	Optional compatibility flag for clients that send full startup configuration. Requires `startupConfig`; on creation there are no saved fields to replace.

Example:

curl -X POST \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "accountId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "appId": "5f7b1b7b7b7b7b7b7b7b7b7c",
        "name": "Production",
        "region": "us-5",
        "branch": "main",
        "zClouds": 2
    }' \
      https://api.quave.cloud/api/public/v1/app-env

Example Response:

{
  "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d"
}

The response contains the appEnvId of the newly created app environment.

Create Branch Preview Environment

To create a temporary branch preview cloned from an existing environment, send a POST request to /api/public/v1/app-env/branch-preview.

This endpoint copies preview-safe AppEnv-scoped runtime settings from the source environment: environment variables (including BUILD/DEPLOY/secret semantics), resources, local persistent-volume settings, startup config, Function config, Job config, WAF/rate-limit settings, IP allowlist settings, and autoscaling settings. It does not copy custom hosts/CNAMEs, TLS/domain bindings, notification/alert delivery destinations, NFS claim attachments, source preview metadata, deployment history/status, one-off credentials, or source preventDestroy.

The endpoint requires a user token with account admin permission, or an internal Operator. Environment tokens are not accepted because the operation copies source environment configuration and secrets.

Field	Type	Required	Description
`appId`	String	Yes	App that owns both the source and preview environments.
`fromAppEnvId`	String	Yes, unless `sourceEnvName` is provided	Source app environment ID. `sourceAppEnvId` remains accepted as a deprecated alias.
`branch`	String	Yes	Git branch to deploy in the preview environment. `branchName` remains accepted as a deprecated alias.
`ttlHours`	Number	Yes	Absolute time-to-live in hours. The server caps the maximum at `168`.
`idleTimeoutHours`	Number	No	Idle timeout in hours. Cleanup deletes the preview when ingress request rate is zero for the entire window.
`preventDestroy`	Boolean	No	Create the preview as protected. Defaults to `false`, even when the source is protected.
`region`	String	No	Target region override. Defaults to the source environment region.
`zClouds`	Number	No	Resource override (`1`, `2`, `4`, or `8`). Defaults to the source value.
`envVars`	Array	No	Full environment-variable override. Omit to copy source env vars.
`startupConfig`	Object	No	Startup config override. Omit to copy source startup config.
`functionConfig`	Object	No	Function config override. Omit to copy source Function config.
`jobConfig`	Object	No	Job config override. Omit to copy source Job config.
`commitSha`	String	No	Source commit SHA stored in metadata and injected as `QUAVEONE_PREVIEW_COMMIT_SHA`.
`sourceEnvName`	String	Yes, unless `fromAppEnvId` is provided	Exact source display name or CLI environment name, scoped to `appId`. Ambiguous matches return `409`.
`wait`	Boolean	No	Accepted for CLI and agent workflows. The endpoint creates the preview and returns the create response.

Branch previews are not supported for Databases & Services environments.

Example:

curl -X POST \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appId": "5f7b1b7b7b7b7b7b7b7b7b7c",
        "fromAppEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d",
        "branch": "feature/checkout-redesign",
        "ttlHours": 12,
        "idleTimeoutHours": 2
    }' \
      https://api.quave.cloud/api/public/v1/app-env/branch-preview

Example Response:

{
  "success": true,
  "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7e",
  "cliEnvName": "acme-web-preview-checkout-redesign",
  "name": "preview-feature-checkout-redesign",
  "branch": "feature/checkout-redesign",
  "fromAppEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d",
  "expiresAt": "2026-07-21T00:00:00.000Z",
  "idleTimeoutHours": 2,
  "cleanupState": "PENDING",
  "preventDestroy": false,
  "hosts": [{ "host": "preview-feature-checkout-redesign.example.com" }],
  "previewUrl": "https://preview-feature-checkout-redesign.example.com",
  "nextDeployCommand": "quaveone deploy --env acme-web-preview-checkout-redesign"
}

Quave ONE injects these system env vars into the preview: QUAVEONE_PREVIEW, QUAVEONE_PREVIEW_BRANCH, QUAVEONE_PREVIEW_SOURCE_ENV_ID, QUAVEONE_PREVIEW_URL, QUAVEONE_PREVIEW_EXPIRES_AT, and QUAVEONE_PREVIEW_COMMIT_SHA when commitSha is provided.

The cleanup job deletes branch previews only when branchPreview metadata exists. It enforces absolute TTL even when ingress metrics are unavailable. When idleTimeoutHours is set, idle cleanup deletes after a successful Prometheus query shows zero request activity for the whole idle window: measured numeric request-rate samples must all be 0. Empty request-rate series, Prometheus query errors, missing metrics identity, and non-numeric samples are treated as unavailable, so the preview is not deleted by idle TTL in that run and branchPreview.cleanupState becomes IDLE_METRICS_UNAVAILABLE with the failure reason. Metrics-unavailable skips do not notify users. If a destroy attempt fails, including a preventDestroy block, Quave ONE notifies the preview creator and current account admins and deduplicates repeated notifications for the same failure reason.

List Branch Preview Environments

Send GET /api/public/v1/app-env/branch-preview?appId=<appId> to list previews for an app. The response is:

{
  "branchPreviews": [
    {
      "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7e",
      "cliEnvName": "acme-web-preview-checkout-redesign",
      "name": "preview-feature-checkout-redesign",
      "branch": "feature/checkout-redesign",
      "fromAppEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d",
      "expiresAt": "2026-07-21T00:00:00.000Z",
      "idleTimeoutHours": 2,
      "cleanupState": "PENDING",
      "preventDestroy": false,
      "hosts": [],
      "previewUrl": "",
      "nextDeployCommand": "quaveone deploy --env acme-web-preview-checkout-redesign"
    }
  ]
}

Extend Branch Preview Environment

Send PATCH /api/public/v1/app-env/branch-preview with either appEnvId or envName, plus a positive additionalTtlHours number. The server refuses to extend any environment without branchPreview metadata. The extension adds the requested hours to the current expiresAt, or to the current time when the preview is already expired; caps each extension request at 168 hours; updates branchPreview.expiresAt, branchPreview.cleanupDueAt, branchPreview.cleanupState, and QUAVEONE_PREVIEW_EXPIRES_AT; and writes an audit event.

{
  "envName": "acme-web-preview-checkout-redesign",
  "additionalTtlHours": 4
}

Delete Branch Preview Environment

Send DELETE /api/public/v1/app-env/branch-preview?envName=<preview-cli-env-name> or DELETE /api/public/v1/app-env/branch-preview?appEnvId=<preview-app-env-id>. The server refuses to delete any environment that does not have branchPreview metadata. preventDestroy=true blocks this delete path exactly like every other AppEnv destroy path.

Databases & Services Presets

Before creating a Databases & Services app or environment through the public API, call GET /api/public/v1/database-presets. The endpoint name is kept for API compatibility even though the presets include databases, caches, and brokers. It returns the automatic DevOps service presets currently supported by the API: MONGODB, POSTGRESQL, MYSQL, REDIS, COUCHDB, RABBITMQ, and CLICKHOUSE. It also returns their version keys, default version, protocol, persistence model, and per-preset disk/replica limits.

Use each preset's returned limits.maxReplicas when setting containers. CouchDB currently supports exactly 1 container.

RabbitMQ environments expose AMQP URLs, MQTT URLs, and a management UI URL in the environment hosts list after deployment. The MQTT external endpoint uses its own generated hostname so it can preserve the allocated external port while still being displayed as mqtt://.

ClickHouse environments expose both HTTP URLs and native clickhouse:// URLs in the environment hosts list after deployment.

Get App Environment

To retrieve an app environment, send a GET request to the /api/public/v1/app-env endpoint. You need to provide the appEnvId as a query parameter.

Query Parameters

Parameter	Type	Required	Description
`appEnvId`	String	Yes	The ID of the app environment to retrieve.
`decrypt`	Boolean	No	Whether to decrypt secret environment variables. Defaults to `false`. Requires admin permission.

Basic Example (without decryption)

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    https://api.quave.cloud/api/public/v1/app-env?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7d

Example Response:

{
  "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d",
  "name": "Production",
  "slug": "production",
  "region": "us-5",
  "status": "RUNNING",
  "currentVersion": 42,
  "gitBranch": "main",
  "cliEnvName": null,
  "allowUserCliToken": false,
  "startupConfig": {
    "command": "bun run start:worker",
    "shell": true,
    "workingDir": "/app"
  },
  "envVars": [
    {
      "_id": "abc123",
      "name": "PUBLIC_VAR",
      "value": "some-value",
      "type": "DEPLOY",
      "isSecret": false
    },
    {
      "_id": "def456",
      "name": "SECRET_KEY",
      "value": "***SECRET***",
      "type": "DEPLOY",
      "isSecret": true
    }
  ]
}

Example with Decryption (Admin Only)

To decrypt secret environment variables, add decrypt=true as a query parameter. This requires admin permission on the account.

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7d&decrypt=true'

Example Response:

{
  "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d",
  "name": "Production",
  "slug": "production",
  "region": "us-5",
  "status": "RUNNING",
  "currentVersion": 42,
  "gitBranch": "main",
  "cliEnvName": null,
  "allowUserCliToken": false,
  "envVars": [
    {
      "_id": "abc123",
      "name": "PUBLIC_VAR",
      "value": "some-value",
      "type": "DEPLOY",
      "isSecret": false
    },
    {
      "_id": "def456",
      "name": "SECRET_KEY",
      "value": "actual-secret-value-123",
      "type": "DEPLOY",
      "isSecret": true
    }
  ]
}

If the user does not have admin permission, the API will return:

{
  "error": "Admin permission required to decrypt secrets"
}

Response Fields

The response contains various fields describing the app environment configuration. Below are the fields returned:

Field	Type	Description
`appEnvId`	String	The app environment ID.
`name`	String	The name of the app environment.
`slug`	String	The slug of the app environment.
`region`	String	The region for the app environment.
`status`	String	Current environment status: `STOPPED`, `PENDING`, `UPDATING`, or `RUNNING`.
`currentVersion`	Number	Version number of the current deployment (null if never deployed).
`gitBranch`	String	The Git branch used for the app environment. For apps that don't use GitHub, the value will be `cli`.
`cliEnvName`	String	The CLI environment name.
`allowUserCliToken`	Boolean	Whether the app environment allows user CLI tokens for deployments.
`preventDestroy`	Boolean	Whether the protected-environment guard blocks destroy/delete operations.
`branchPreview`	Object	Branch-preview lifecycle metadata when this environment was created as a branch preview.
`envVars`	Array	Array of environment variables. See Environment Variables Object.
`startupConfig`	Object	Saved environment startup override, when configured. See Startup Config Object.
`jobConfig`	Object	Job environment overrides when this environment belongs to a Job app.
`appJobConfig`	Object	App-level Job defaults inherited by this environment.

Note: Secret environment variables will have their values masked as ***SECRET*** unless decrypt=true is provided with admin credentials.

Set Prevent Destroy

To enable or disable the protected-environment guard, send a PATCH request to /api/public/v1/app-env/prevent-destroy.

This endpoint requires a user token with the same account admin permission required to delete the environment. Environment tokens are not accepted. MCP requests must also include the dedicated quave:admin:destroy-protection scope; quave:write:dangerous alone is not enough because this endpoint controls the safety lock that can block or allow future destructive actions. Every successful toggle creates an audit event.

curl -X PATCH \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d",
        "preventDestroy": true
    }' \
      https://api.quave.cloud/api/public/v1/app-env/prevent-destroy

When preventDestroy is true, dashboard, Public API, MCP, CLI-backed, cleanup-job, and internal destroy paths fail before deleting the environment. This also blocks deleting the parent app or account because those actions would destroy the protected environment. Disable preventDestroy before deleting a protected environment.

Update App Environment

To update an existing app environment, send a PUT request to the /api/public/v1/app-env endpoint. All fields are optional - only provide the fields you want to update.

Request Body Fields

Field	Type	Required	Description
`appEnvId`	String	Yes	The ID of the app environment to update.
`name`	String	No	The new name for the app environment.
`region`	String	No	The new region for the app environment (must be one of the allowed values).
`branch`	String	No	The new Git branch to use. Cannot be empty for apps that use GitHub.
`zClouds`	Number	No	The new number of zClouds to use (1, 2, 4, or 8).
`envVars`	Array	No	The new environment variables. See Environment Variables Object.
`containers`	Integer	No	The new number of containers for managed database environments.
`disk`	Integer	No	The new allocated disk size in MB for managed database environments or regular app environments with a local persistent volume (`useVolume=true` and `useNfsVolume=false`). Applied persistent disks are grow-only: the value may stay the same or increase, but decreases are rejected. Shared NFS volumes and stateless apps do not use this disk setting. Starting with July 2026 billing, eligible Direct local disk above the included `zClouds * 5 GB` allowance is billed as storage overage. See pricing.
`databaseSettings`	Object	No	Database engine settings. See Database Settings Object.
`functionConfig`	Object	No	Function settings (only for function apps). See Function Config Object.
`jobConfig`	Object	No	Job settings (only for Job apps). See Job Config Object.
`startupConfig`	Object	No	Partial startup configuration patch. Omitted nested fields preserve their saved values. Not supported for Jobs or Databases & Services. See Startup Config Object.
`clearStartupConfig`	Boolean	No	Set to `true` to remove the complete startup override. Cannot be combined with `startupConfig`.
`replaceStartupConfig`	Boolean	No	Set to `true` with `startupConfig` to replace the complete saved override and remove omitted fields. Cannot be combined with `clearStartupConfig`.

Note: When updating envVars, the entire array replaces the existing environment variables. Make sure to include all environment variables you want to keep.

Function Config Object

Only applicable to function apps. All fields are optional integers.

Field	Type	Description
`containerConcurrency`	Integer	Max concurrent requests per container.
`timeoutSeconds`	Integer	Request timeout in seconds.
`idleTimeoutSeconds`	Integer	Idle timeout before scale-to-zero (minimum 300).
`responseStartTimeoutSeconds`	Integer	Timeout for the first byte of response.
`minScale`	Integer	Minimum number of container instances.
`maxScale`	Integer	Maximum number of container instances.

Job Config Object

Only applicable to Job apps. All fields are optional on the app environment, but a command must be available from the applied Job config snapshot or a per-run override before a Job can run.

Field	Type	Description
`command`	String	Command to execute for each run.
`args`	Array of strings	Optional argument list.
`shell`	Boolean	Runs through `/bin/sh -lc` when true. Default: true.
`workingDir`	String	Working directory inside the container.
`timeoutSeconds`	Integer	Active deadline for a run. Default: 1800.
`ttlSecondsAfterFinished`	Integer	Kubernetes TTL after completion. Default: 21600.
`backoffLimit`	Integer	Kubernetes Job retry backoff limit. Default: 0.
`maxConcurrency`	Integer	Maximum active runs for this Job environment.
`allowConcurrentRuns`	Boolean	Allows unlimited concurrent runs when true and `maxConcurrency` is omitted.

Startup Config Object

Only applicable to regular Apps and Functions. A complete configuration must include at least one of command, a non-empty args array, or workingDir. For a partial update of an existing configuration, shell can be sent by itself, and args: [] removes the saved arguments. The final merged configuration must still be valid.

Field	Type	Description
`command`	String	Complete command line when `shell` is `true`, or one exact executable when `shell` is `false`.
`args`	Array of strings	Exact arguments. With no saved command, args-only preserves the image `ENTRYPOINT` and replaces its `CMD`.
`shell`	Boolean	Runs the command through `/bin/sh -lc` when `true`. A new command defaults to `true`.
`workingDir`	String	Working directory inside the container. Can be used by itself.

Startup configuration is persisted on the environment. Updates are partial by default: fields omitted from startupConfig keep their saved values. Therefore sending only args to an environment that already has a command updates the arguments for that command. Set replaceStartupConfig: true in the same request when startupConfig is the complete desired override and omitted fields must be removed.

Example: Update Name and zClouds

curl -X PUT \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d",
        "name": "Production v2",
        "zClouds": 4
    }' \
    https://api.quave.cloud/api/public/v1/app-env

Example: Update Environment Variables

curl -X PUT \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d",
        "envVars": [
            {
                "name": "API_KEY",
                "value": "new-api-key-value",
                "type": "DEPLOY",
                "isSecret": true
            },
            {
                "name": "DEBUG",
                "value": "true",
                "type": "BOTH",
                "isSecret": false
            }
        ]
    }' \
    https://api.quave.cloud/api/public/v1/app-env

Example: Update Startup Command

curl -X PUT \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d",
        "startupConfig": {
          "command": "bun run start:worker",
          "shell": true,
          "workingDir": "/app"
        },
        "replaceStartupConfig": true
    }' \
    https://api.quave.cloud/api/public/v1/app-env

This saves a pending deploy change. Apply it with POST /api/public/v1/app-env/apply-changes or include it in the next deploy.

Example: Clear Startup Override

curl -X PUT \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d",
        "clearStartupConfig": true
    }' \
    https://api.quave.cloud/api/public/v1/app-env

Example Response

{
  "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d"
}

Notes

Secret environment variables will be automatically encrypted before storage
If you're updating the region, the system will mark the environment as "changing region" and trigger necessary infrastructure updates
Changes to resources (zClouds or persistent disk), branch, environment variables, Job config, or startup config generate "pending changes" that are applied through the Apply Changes flow
Do not put secrets in startup commands or arguments. Use secret runtime environment variables instead.

Update Job Config

Updates the command and execution defaults for a Job app environment. Only available for apps using the JOB docker preset.

Use this endpoint when you want to edit an existing Job environment after creation. These values override the app-level jobConfig; leave command, args, or workingDir empty to clear the environment override and inherit the app-level default.

Saving this endpoint creates pending deploy changes by default. Default JobRuns continue to use the previously applied Job config snapshot until the pending changes are applied with POST /api/public/v1/app-env/apply-changes, the MCP tool apply-app-env-changes, the dashboard Apply changes action, or applyImmediately: true.

Environment tokens scoped to the target environment can save pending Job config changes. They cannot use applyImmediately: true; applying changes immediately requires a user token.

Endpoint: PATCH /api/public/v1/app-env/job-config

Request Body

You must provide either appEnvId or envName.

Field	Type	Required	Description
`appEnvId`	String	No	App environment ID. Required if `envName` is not provided.
`envName`	String	No	CLI environment name. Required if `appEnvId` is not provided.
`jobConfig`	Object	No	Nested Job config object. Top-level fields override matching nested fields.
`command`	String	No	Command to execute for each JobRun. Empty clears the environment override.
`args`	Array of strings	No	Optional argument list. Empty clears the environment override.
`shell`	Boolean	No	Runs through `/bin/sh -lc` when true.
`workingDir`	String	No	Working directory inside the container. Empty clears the override.
`timeoutSeconds`	Integer	No	Active deadline for one JobRun in seconds.
`ttlSecondsAfterFinished`	Integer	No	Kubernetes TTL after a JobRun finishes, minimum 300 seconds.
`backoffLimit`	Integer	No	Kubernetes retry backoff limit.
`maxConcurrency`	Integer	No	Maximum active JobRuns for this environment.
`allowConcurrentRuns`	Boolean	No	Allows unlimited active runs when true and `maxConcurrency` is omitted.
`applyImmediately`	Boolean	No	If true, apply pending changes immediately with a user token. Default: false.

Example

curl -X PATCH \
  -H 'Authorization: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "appEnvId": "APP_ENV_ID",
    "command": "bin/rails db:migrate",
    "timeoutSeconds": 900,
    "backoffLimit": 0
  }' \
  https://api.quave.cloud/api/public/v1/app-env/job-config

Example Response

{
  "success": true,
  "appEnv": {
    "appEnvId": "APP_ENV_ID",
    "pendingChanges": {
      "hasDeployChanges": true,
      "deployPendingChanges": [
        {
          "group": "Job Settings",
          "field": "jobConfig"
        }
      ]
    }
  },
  "jobConfig": {
    "command": "bin/rails db:migrate",
    "timeoutSeconds": 900,
    "backoffLimit": 0
  },
  "appliedImmediately": false
}

Notes

applyImmediately: false is the default. It saves the config and exposes the change in pendingChanges.
applyImmediately: true applies the saved Job config snapshot immediately and returns appliedImmediately: true.
A run created before applying the pending change still uses the previously applied command unless that run includes a per-run jobConfig override.
Historical JobRuns keep their original command snapshot.

Update Function Config

Updates the scaling and timeout configuration for a function app environment. Only available for apps using the FUNCTION docker preset.

Endpoint: PATCH /api/public/v1/app-env/function-config

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).
`containerConcurrency`	Integer	No	Maximum concurrent requests per container.
`timeoutSeconds`	Integer	No	Request timeout in seconds.
`idleTimeoutSeconds`	Integer	No	Idle timeout before scale-to-zero in seconds (minimum 300).
`responseStartTimeoutSeconds`	Integer	No	Timeout for the first byte of response in seconds.
`minScale`	Integer	No	Minimum number of container instances. 0 allows scale-to-zero.
`maxScale`	Integer	No	Maximum number of container instances. Subject to account limits.
`applyImmediately`	Boolean	No	If true, deploy changes immediately. Default: false.

Example

curl -X PATCH \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d",
        "containerConcurrency": 80,
        "timeoutSeconds": 300,
        "idleTimeoutSeconds": 600,
        "minScale": 0,
        "maxScale": 10,
        "applyImmediately": true
    }' \
    https://api.quave.cloud/api/public/v1/app-env/function-config

Example Response

{
  "success": true,
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7d",
    "name": "Production",
    "status": "UPDATING",
    "isFunction": true,
    "functionConfig": {
      "containerConcurrency": 80,
      "timeoutSeconds": 300,
      "idleTimeoutSeconds": 600,
      "minScale": 0,
      "maxScale": 10
    }
  },
  "appliedImmediately": true
}

Notes

This endpoint returns an error if the app does not use the FUNCTION docker preset.
Values for maxScale, minScale, and idleTimeoutSeconds are enforced against account-level limits.
If applyImmediately is false (default), changes are stored as pending changes and applied on the next deployment or when using the apply-changes endpoint.
You can also update function config through the general Update App Environment endpoint by passing a functionConfig object.

For more details about functions, see the Functions documentation.

Delete App Environment

To delete an app environment, send a DELETE request to the /api/public/v1/app-env endpoint. You need to provide the appEnvId as a query parameter.

Example:

curl -X DELETE \
    -H 'Authorization: YOUR_TOKEN' \
    https://api.quave.cloud/api/public/v1/app-env?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7d

Example Response:

{
  "message": "App Env deleted successfully"
}

Note: Deleting an app environment may have significant consequences. Make sure you want to perform this action before proceeding. For automatically provisioned Databases & Services environments, this endpoint deletes the Quave ONE records and the managed Kubernetes resources, including RabbitMQ. Persistent database volumes are retained for the separate PVC cleanup/detach flow. Manual database environments are not supported by this API delete path. When preventDestroy is enabled, deletion fails until the guard is disabled; it also blocks deleting the parent app or account.

Environment Variables Object

The envVars field is an array of environment variables. Each environment variable is an object with the following fields:

Field	Type	Description
`name`	String	The environment variable name.
`value`	String	The environment variable value.
`type`	String	The type of the environment variable. Possible values are `DEPLOY`, `BUILD`, or `BOTH`.
`isSecret`	Boolean	Whether the environment variable is secret and should be encrypted. Default: true.

Database Settings Object

The databaseSettings field configures managed database environments. Only pass the settings block for the database engine used by the environment.

MySQL Settings

For MySQL environments, pass databaseSettings.mysql.parameters.

Parameter	Type	Description
`max_connections`	Integer	Maximum simultaneous client connections, from 1 through 100000.

Example:

{
  "databaseSettings": {
    "mysql": {
      "parameters": {
        "max_connections": 250
      }
    }
  }
}

Tuning parameters above are mutable and applied on the next deploy.

PostgreSQL Settings

For PostgreSQL environments, pass databaseSettings.postgresql.parameters.

Parameter	Type	Description
`work_mem`	String	Per-operation memory value, such as `16MB` or `24MB`.
`hash_mem_multiplier`	Number	Hash operation multiplier.
`max_parallel_workers_per_gather`	Integer	Maximum parallel workers per gather, from 0 through 64.
`effective_cache_size`	String	Planner cache size estimate, such as `1536MB` or `6GB`.

Example:

{
  "databaseSettings": {
    "postgresql": {
      "parameters": {
        "work_mem": "16MB",
        "hash_mem_multiplier": 1,
        "max_parallel_workers_per_gather": 2,
        "effective_cache_size": "1536MB"
      }
    }
  }
}

Tuning parameters above are mutable and applied on the next deploy.

MongoDB Settings

For MongoDB 8.2 or newer environments, pass databaseSettings.mongodb.search.enabled to provision MongoDB Search (mongot) alongside the managed replica set.

Example:

{
  "dockerPreset": "MONGODB",
  "dockerPresetVersion": "MONGODB_8",
  "databaseSettings": {
    "mongodb": {
      "search": {
        "enabled": true
      }
    }
  }
}

MongoDB Search is optional and only supported for managed MongoDB 8.2 or newer environments. When enabled, Quave ONE creates and monitors a separate Search pod and volume after the MongoDB replica set is running.

Engine version and image are immutable

The dockerPresetVersion you pick at creation also selects the container image and, for PostgreSQL, the underlying engine variant. PostgreSQL-compatible variants such as TimescaleDB and ParadeDB run on a custom image (and TimescaleDB also pins a non-default user id) that is wired into the cluster when it is first created.

The image, the PostgreSQL major version, and the user/group ids are fixed for the life of the cluster. Changing dockerPresetVersion on an existing database environment is not supported, so the value is read-only after creation in the dashboard. To move to a different engine variant or major version, create a new database with the desired dockerPresetVersion and migrate your data into it.

Create App Environment​

Create Branch Preview Environment​

List Branch Preview Environments​

Extend Branch Preview Environment​

Delete Branch Preview Environment​

Databases & Services Presets​

Get App Environment​

Query Parameters​

Basic Example (without decryption)​

Example with Decryption (Admin Only)​

Response Fields​

Set Prevent Destroy​

Update App Environment​

Request Body Fields​

Function Config Object​

Job Config Object​

Startup Config Object​

Example: Update Name and zClouds​

Example: Update Environment Variables​

Example: Update Startup Command​

Example: Clear Startup Override​

Example Response​

Notes​

Update Job Config​

Request Body​

Example​

Example Response​

Notes​

Update Function Config​

Request Body​

Example​

Example Response​

Notes​

Delete App Environment​

Environment Variables Object​

Database Settings Object​

MySQL Settings​

PostgreSQL Settings​

MongoDB Settings​

Engine version and image are immutable​

Create App Environment

Create Branch Preview Environment

List Branch Preview Environments

Extend Branch Preview Environment

Delete Branch Preview Environment

Databases & Services Presets

Get App Environment

Query Parameters

Basic Example (without decryption)

Example with Decryption (Admin Only)

Response Fields

Set Prevent Destroy

Update App Environment

Request Body Fields

Function Config Object

Job Config Object

Startup Config Object

Example: Update Name and zClouds

Example: Update Environment Variables

Example: Update Startup Command

Example: Clear Startup Override

Example Response

Notes

Update Job Config

Request Body

Example

Example Response

Notes

Update Function Config

Request Body

Example

Example Response

Notes

Delete App Environment

Environment Variables Object

Database Settings Object

MySQL Settings

PostgreSQL Settings

MongoDB Settings

Engine version and image are immutable