App Environment Configuration API

The App Environment Configuration API allows you to manage configuration settings for app environments in Quave ONE, 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": "main",
        "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": "main"
  },
  "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:

Basic Mode (default): Use a single path for all probes (readiness, liveness, startup)
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, security context, and basic authentication.

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.
`basicAuthAccountSecretId`	String	No	ID of a Basic Auth credential. Empty string clears. See Credentials API.
`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 IP Allowlist

Manages the IP address allowlist and network control for an app environment. Use networkControlEnabled to toggle IP restriction enforcement. When an allowlist has active entries and network control is enabled, only connections from listed IP addresses are allowed. Changes trigger an immediate deploy (no pending changes workflow) since they are security-critical.

Endpoint: PUT /api/public/v1/app-env/allowlist

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).
`networkControlEnabled`	Boolean	No	Enable or disable IP address restrictions. When `false`, all connections are allowed. When `true`, only active allowlist entries are permitted.
`entries`	Array	No	Entries to add or update (matched by `ipAddress`). At least one of `entries`, `entriesToRemove`, or `networkControlEnabled` is required.
`entriesToRemove`	String[]	No	Array of entry IDs to remove. Get IDs from the get-app-env response. Removals happen before adds/updates.

Entry Object

Field	Type	Required	Description
`ipAddress`	String	Yes	IP address or CIDR range (e.g., `192.168.1.0/24`, `10.0.0.1`). Use `*` to allow any IP.
`description`	String	No	Human-readable description for this entry.
`deleteEntry`	String	No	Auto-expiration: `NEVER`, `AFTER_6H`, `AFTER_12H`, `AFTER_A_DAY`, `AFTER_A_WEEK`, `AFTER_A_MONTH`. Default: `NEVER`.
`isActive`	Boolean	No	Whether this entry is active. Inactive entries are ignored during deploy. Default: `true`.

Example: Add entries

curl -X PUT \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "entries": [
            {
                "ipAddress": "203.0.113.0/24",
                "description": "Office network",
                "deleteEntry": "NEVER",
                "isActive": true
            },
            {
                "ipAddress": "198.51.100.50",
                "description": "VPN server",
                "deleteEntry": "AFTER_A_WEEK"
            }
        ]
    }' \
    https://api.quave.cloud/api/public/v1/app-env/allowlist

Example: Remove entries

curl -X PUT \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "entriesToRemove": ["entry-id-1", "entry-id-2"]
    }' \
    https://api.quave.cloud/api/public/v1/app-env/allowlist

Example Response

{
  "success": true,
  "message": "IP allowlist updated and deploy triggered",
  "addressAllowlist": [
    {
      "_id": "abc123",
      "ipAddress": "203.0.113.0/24",
      "description": "Office network",
      "deleteEntry": "NEVER",
      "isActive": true,
      "createdAt": "2025-01-20T14:00:00.000Z"
    }
  ],
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production"
  }
}

Example: Toggle network control

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

Notes

Network control: Use networkControlEnabled to toggle IP restriction enforcement without modifying allowlist entries. When disabled, all connections are allowed regardless of entries.
Partial updates: Use entries to add or update (matched by IP address) and entriesToRemove to delete by entry ID. Removals happen first, then adds/updates.
Immediate deploy: Changes are deployed immediately without going through the pending changes workflow, as IP allowlist changes are security-critical.
View current allowlist: Use the get-app-env endpoint to see the current addressAllowlist array and networkControlEnabled state.
Auto-expiration: Entries with a deleteEntry value other than NEVER are automatically removed by a background job after the specified time.

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`.

Update Git Branch​

Request Body​

Example​

Example Response​

Notes​

Update HTTP Probes​

Configuration Modes​

Request Body​

Probe Object Fields​

Example: Basic Mode (Enable Probes)​

Example: Advanced Mode (Individual Probes)​

Example: Disable HTTP Probes​

Example Response​

Notes​

Update Security Settings​

Request Body​

Example: Enable WAF and Rate Limiting​

Example: Set Security Context​

Example: Clear Rate Limiting​

Example Response​

Notes​

Update IP Allowlist​

Request Body​

Entry Object​

Example: Add entries​

Example: Remove entries​

Example Response​

Example: Toggle network control​

Notes​

Update Environment Name​

Request Body​

Example​

Example Response​

Error Responses​

Update Git Branch

Request Body

Example

Example Response

Notes

Update HTTP Probes

Configuration Modes

Request Body

Probe Object Fields

Example: Basic Mode (Enable Probes)

Example: Advanced Mode (Individual Probes)

Example: Disable HTTP Probes

Example Response

Notes

Update Security Settings

Request Body

Example: Enable WAF and Rate Limiting

Example: Set Security Context

Example: Clear Rate Limiting

Example Response

Notes

Update IP Allowlist

Request Body

Entry Object

Example: Add entries

Example: Remove entries

Example Response

Example: Toggle network control

Notes

Update Environment Name

Request Body

Example

Example Response

Error Responses