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 Health Check

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

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

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).
healthCheckPath	String	No	Path to check for health (e.g., "/api/health"). Set to empty/null to clear.
healthCheckPort	Number	No	Port to check. If not set, uses app port. Set to null to clear.
healthCheckHeaders	Object	No	Custom headers to send (e.g., {"X-Custom": "value"}). Set to null/empty to clear.
applyImmediately	Boolean	No	If true, deploy changes immediately. Default: false.

Example: Set Health Check

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

Example: Clear Health Check

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

Example Response

{
  "success": true,
  "message": "Health check configuration updated and changes applied",
  "healthCheck": {
    "path": "/api/health",
    "port": 3000,
    "headers": {
      "X-Health-Check": "true"
    }
  },
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production"
  },
  "environmentsAffected": 2,
  "appliedImmediately": true
}

Notes

• Health check is app-level - changes affect all environments of the app.
• environmentsAffected shows how many environments were updated.

---

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.