App Environment Configuration API

The App Environment Configuration API allows you to manage configuration settings for app environments in Quave Cloud, including git branch, health checks, security settings, and environment name.

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.

Update Git Branch

Updates the git branch for an app environment. Changing the branch creates pending build changes that require a new build.

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

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).
gitBranch	String	Yes	The git branch name to deploy from (e.g., "main").
applyImmediately	Boolean	No	If true, trigger build immediately. Default: false.

Example

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

Example Response

{
  "success": true,
  "message": "Git branch updated and build triggered",
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production",
    "gitBranch": "develop"
  },
  "appliedImmediately": true
}

Notes

• Changing the branch always creates pending build changes (not just deploy changes).
• If applyImmediately: true, a new build will be triggered from the specified branch.

---

Update HTTP Probes

Updates the HTTP probes (health check) configuration for an app. Probe settings are app-level and shared across all environments of the app.

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

Configuration Modes

The API supports two configuration modes:

1. Basic Mode (default): Use a single path for all probes (readiness, liveness, startup)
2. Advanced Mode: Configure each probe individually with path, periodSeconds, and failureThreshold

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).
enableHttpProbes	Boolean	No	Master toggle to enable/disable HTTP probes.
isConfigurationByProbeEnabled	Boolean	No	Enable advanced mode with individual probe configs.
healthCheckPath	String	No	Path for basic mode (used for all probes). Set to empty/null to clear.
healthCheckPort	Number	No	Port to check. If not set, uses app port. Set to null to clear.
livenessProbe	Object	No*	Liveness probe config. *Required when advanced mode enabled.
readinessProbe	Object	No*	Readiness probe config. *Required when advanced mode enabled.
startupProbe	Object	No*	Startup probe config. *Required when advanced mode enabled.
applyImmediately	Boolean	No	If true, deploy changes immediately. Default: false.

Probe Object Fields

Each probe object (livenessProbe, readinessProbe, startupProbe) contains:

Field	Type	Required	Description
path	String	Yes	HTTP path to check (e.g., "/health").
periodSeconds	Number	Yes	How often to perform the probe (in seconds).
failureThreshold	Number	Yes	Consecutive failures before taking action.

Example: Basic Mode (Enable Probes)

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

Example: Advanced Mode (Individual Probes)

When using advanced mode, all 9 fields (3 probes x 3 fields) are required.

curl -X PATCH \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "enableHttpProbes": true,
        "isConfigurationByProbeEnabled": true,
        "readinessProbe": {
            "path": "/ready",
            "periodSeconds": 10,
            "failureThreshold": 3
        },
        "livenessProbe": {
            "path": "/health",
            "periodSeconds": 30,
            "failureThreshold": 5
        },
        "startupProbe": {
            "path": "/started",
            "periodSeconds": 5,
            "failureThreshold": 30
        },
        "applyImmediately": true
    }' \
    https://api.quave.cloud/api/public/v1/app-env/healthcheck

Example: Disable HTTP Probes

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

Example Response

{
  "success": true,
  "message": "HTTP probes configuration updated and changes applied",
  "probesConfig": {
    "enableHttpProbes": true,
    "isConfigurationByProbeEnabled": true,
    "healthCheckPath": null,
    "healthCheckPort": null,
    "livenessProbe": {
      "path": "/health",
      "periodSeconds": 30,
      "failureThreshold": 5
    },
    "readinessProbe": {
      "path": "/ready",
      "periodSeconds": 10,
      "failureThreshold": 3
    },
    "startupProbe": {
      "path": "/started",
      "periodSeconds": 5,
      "failureThreshold": 30
    }
  },
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production"
  },
  "environmentsAffected": 2,
  "appliedImmediately": true
}

Notes

• HTTP probes configuration is app-level - changes affect all environments of the app.
• environmentsAffected shows how many environments were updated.
• When isConfigurationByProbeEnabled is true, all 9 probe fields are required.
• Learn more about HTTP probes in the HTTP Probes documentation.

---

Update Security Settings

Updates security settings for an app environment including ModSecurity WAF (Web Application Firewall), rate limiting, and security context.

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

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).
enableModSecurity	Boolean	No	Enable/disable OWASP ModSecurity WAF.
limitConnections	Number	No	Max concurrent connections per IP per controller replica.
limitRPS	Number	No	Max requests per second per IP per container.
limitRPM	Number	No	Max requests per minute per IP per container.
clearRateLimit	Boolean	No	Set to true to clear all rate limit settings.
fsGroup	Number	No	File system group ID for volume mounts.
runAsUser	Number	No	UID to run the container process as.
runAsGroup	Number	No	GID to run the container process as.
clearSecurityContext	Boolean	No	Set to true to clear all security context settings.
applyImmediately	Boolean	No	If true, deploy changes immediately. Default: false.

Example: Enable WAF and Rate Limiting

curl -X PATCH \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "enableModSecurity": true,
        "limitConnections": 150,
        "limitRPS": 100,
        "limitRPM": 3000,
        "applyImmediately": true
    }' \
    https://api.quave.cloud/api/public/v1/app-env/security

Example: Set Security Context

curl -X PATCH \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "fsGroup": 1001,
        "runAsUser": 1001,
        "runAsGroup": 1001
    }' \
    https://api.quave.cloud/api/public/v1/app-env/security

Example: Clear Rate Limiting

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

Example Response

{
  "success": true,
  "message": "Security settings updated and changes applied",
  "securitySettings": {
    "enableModSecurity": true,
    "rateLimit": {
      "limitConnections": 150,
      "limitRPS": 100,
      "limitRPM": 3000
    },
    "securityContext": {}
  },
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production"
  },
  "appliedImmediately": true
}

Notes

• ModSecurity: OWASP Web Application Firewall helps protect against common web attacks (XSS, SQL injection, etc.).
• Rate Limiting: Protects against DDoS and brute force attacks. Returns 503 error when limits are exceeded.
• Security Context: Useful for resolving permission issues with mounted volumes.
• All parameters are flat (no nested objects required), making the API easier to use.

---

Update Environment Name

Updates the display name of an app environment. This may affect CLI deploy targets if you use the name for identification.

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

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).
name	String	Yes	The new name for the environment.
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": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "name": "Production v2",
        "applyImmediately": true
    }' \
    https://api.quave.cloud/api/public/v1/app-env/name

Example Response

{
  "success": true,
  "message": "Environment name updated and changes applied",
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production v2"
  },
  "appliedImmediately": true
}

---

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.