App Environments API

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

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

Note: All endpoints in this API accept only the user token.

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.

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.

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.

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.
`functionConfig`	Object	No	Function settings (only for function apps). See Function 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.

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, or environment variables will generate "pending changes" that will be applied on the next deployment

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.

Create App Environment​

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​

Example: Update Name and zClouds​

Example: Update Environment Variables​

Example Response​

Notes​

Update Function Config​

Request Body​

Example​

Example Response​

Notes​

Delete App Environment​

Environment Variables Object​

Create App Environment

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

Example: Update Name and zClouds

Example: Update Environment Variables

Example Response

Notes

Update Function Config

Request Body

Example

Example Response

Notes

Delete App Environment

Environment Variables Object