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",
  "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",
  "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.
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.

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

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

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.