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 for managed database environments, in MB.
`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.

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.

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,
  "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.
`envVars`	Array	Array of environment variables. See Environment Variables 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.

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 disk size for managed database environments, in MB.
`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.

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. Functions are available starting from the Quave ONE Connect plan. 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.

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 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), branch, environment variables, or Job config generate "pending changes" that are applied through the Apply Changes flow

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": "bundle exec 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": "bundle exec 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. Functions are available starting from the Quave ONE Connect plan.

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.

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.

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.

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​

Databases & Services Presets​

Get App Environment​

Query Parameters​

Basic Example (without decryption)​

Example with Decryption (Admin Only)​

Response Fields​

Update App Environment​

Request Body Fields​

Function Config Object​

Job Config Object​

Example: Update Name and zClouds​

Example: Update Environment Variables​

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​

PostgreSQL Settings​

Engine version and image are immutable​

Create App Environment

Databases & Services Presets

Get App Environment

Query Parameters

Basic Example (without decryption)

Example with Decryption (Admin Only)

Response Fields

Update App Environment

Request Body Fields

Function Config Object

Job Config Object

Example: Update Name and zClouds

Example: Update Environment Variables

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

PostgreSQL Settings

Engine version and image are immutable