App Environment Deployments API

The App Environment Deployments API allows you to manage deployments, builds, and lifecycle operations for app environments in Quave ONE.

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.

Deploy Image

Deploys a Docker image directly to an app environment, skipping the build step. The app must be configured with useImage=true or be a function app.

Endpoint: POST /api/public/v1/app-env/deploy-image

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).
`image`	String	Yes	The Docker image to deploy (e.g., `registry/image:tag`).
`envVars`	Object	No	CLI-compatible map of environment variable names to string values.
`functionConfig`	Object	No	Function scaling and timeout fields to merge before the deployment.
`startupConfig`	Object	No	Partial persistent startup configuration update. See Startup Configuration.
`clearStartupConfig`	Boolean	No	Set to `true` to clear the complete saved startup override. Cannot be combined with `startupConfig`.
`replaceStartupConfig`	Boolean	No	Set to `true` with `startupConfig` to replace the complete saved override instead of merging a patch. Cannot be combined with `clearStartupConfig`.

Example

curl -X POST \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "image": "my-registry.com/my-app:v1.2.3",
        "startupConfig": {
          "command": "bun run start:worker",
          "shell": true
        },
        "replaceStartupConfig": true,
        "envVars": {
          "RELEASE_CHANNEL": "stable"
        }
    }' \
    https://api.quave.cloud/api/public/v1/app-env/deploy-image

For function apps, functionConfig accepts containerConcurrency, timeoutSeconds, idleTimeoutSeconds, responseStartTimeoutSeconds, minScale, and maxScale.

Example Response

{
  "success": true,
  "message": "Deployment triggered for image my-registry.com/my-app:v1.2.3",
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production",
    "status": "UPDATING"
  }
}

Notes

Function apps can use this endpoint to deploy images directly without useImage=true.
For non-function apps, useImage must be enabled on the app first.
Environment variables are merged by name. Existing variables not included in envVars remain unchanged; new variables default to secret runtime variables.
Function configuration is merged with the saved configuration and remains subject to the account's function limits.
Environment variables and function configuration are saved before the image deployment is triggered, so the new deployment uses the updated values.
Startup configuration is saved before deployment and remains associated with the environment for later image versions and redeploys.
Every image deployment request creates a fresh content version, even when the image reference matches the current version. The returned contentId identifies this specific deployment and can be used for exact status polling.
Startup configuration is supported for regular Apps and Functions, but not for Jobs or Databases & Services.
Use the dedicated environment-variable and function-configuration endpoints when you need removals or explicit variable metadata.

Startup Configuration

startupConfig can contain command, args, shell, and workingDir. Updates are partial by default, so omitted nested fields preserve their saved values. Set replaceStartupConfig: true in the same request when the supplied object is the complete desired override; omitted fields are then removed. A new command defaults to shell: true; use shell: false with one exact executable and an args array for direct mode. With no saved command, args-only preserves the image ENTRYPOINT and replaces its CMD. A working-directory-only override is also valid.

Use clearStartupConfig: true to restore the image ENTRYPOINT, CMD, and working directory. For all semantics and examples, see Startup Command Overrides.

Trigger Build

Triggers a new build for an app environment. This starts the build process to create a new deployment artifact from the configured git branch.

Endpoint: POST /api/public/v1/app-env/build

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).
`forceNewBuild`	Boolean	No	Force a new build even if no code changes detected. Default: false.
`isRebuild`	Boolean	No	Whether this is a rebuild of existing content. Default: false.
`fromContentId`	String	No	Content ID to rebuild from. Used with `isRebuild: true`.
`startupConfig`	Object	No	Partial persistent startup configuration update applied to the resulting deployment.
`clearStartupConfig`	Boolean	No	Clear the complete saved startup override before building. Cannot be combined with `startupConfig`.
`replaceStartupConfig`	Boolean	No	Replace the complete saved startup override with `startupConfig` before building.

Example: Trigger New Build

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

Example: Force New Build

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

Example: Build Source with a Worker Command

curl -X POST \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "startupConfig": {
          "command": "bun run start:worker",
          "shell": true
        },
        "replaceStartupConfig": true
    }' \
    https://api.quave.cloud/api/public/v1/app-env/build

The startup override is runtime configuration. It is saved before the build but is not included in the build hash, so changing it does not make the source image different or prevent image reuse.

Example: Rebuild from Previous Version

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

Example Response

{
  "success": true,
  "message": "Build triggered successfully",
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production",
    "status": "UPDATING"
  }
}

Redeploy

Redeploys an app environment using the current or a specified deployment version. This restarts the containers with the existing build artifact.

Endpoint: POST /api/public/v1/app-env/redeploy

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).
`contentId`	String	No	Content ID to redeploy. If not provided, redeploys current version.

Example: Redeploy Current Version

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

Example: Redeploy Specific Version

curl -X POST \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "contentId": "abc123def456"
    }' \
    https://api.quave.cloud/api/public/v1/app-env/redeploy

Example Response

{
  "success": true,
  "message": "Redeploy triggered successfully",
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production",
    "status": "UPDATING"
  }
}

Use Cases

Restart Containers: Redeploy the current version to restart all containers.
Apply Configuration Changes: After updating environment variables or resources, redeploy to apply changes.
Recover from Issues: Redeploy if containers are in an unhealthy state.

Rollback

Rolls back an app environment to a previous version. If no targetContentId is specified, rolls back to the immediately previous deployment.

Endpoint: POST /api/public/v1/app-env/rollback

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).
`targetContentId`	String	No	Content ID to rollback to. If not provided, uses previous version.

Example: Rollback to Previous Version

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

Example: Rollback to Specific Version

curl -X POST \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
        "targetContentId": "abc123def456"
    }' \
    https://api.quave.cloud/api/public/v1/app-env/rollback

Example Response

{
  "success": true,
  "message": "Rollback triggered successfully",
  "rollbackInfo": {
    "fromVersion": 42,
    "toVersion": 41,
    "contentId": "abc123def456"
  },
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production",
    "status": "UPDATING"
  }
}

Notes

Dangerous Operation: Rollback replaces the current deployment with a previous version.
Use the App Environment History API to get available contentId values.
You cannot rollback to the currently deployed version.

Stop Environment

Stops an app environment by scaling its containers to zero. The environment can be started again later.

Endpoint: POST /api/public/v1/app-env/stop

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

Example

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

Example Response

{
  "success": true,
  "message": "Environment stop triggered",
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production",
    "status": "UPDATING"
  }
}

Notes

Dangerous Operation: Stopping an environment makes it unreachable.
The environment status will change to STOPPED once the operation completes.
Use the Start Environment endpoint to restart.

Start Environment

Starts a stopped app environment by redeploying its current version.

Endpoint: POST /api/public/v1/app-env/start

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

Example

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

Example Response

{
  "success": true,
  "message": "Environment start triggered",
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production",
    "status": "UPDATING"
  }
}

Notes

The environment must have been deployed at least once before it can be started.
The environment status will change to RUNNING once the operation completes.

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

Deploy Image​

Request Body​

Example​

Example Response​

Notes​

Startup Configuration​

Trigger Build​

Request Body​

Example: Trigger New Build​

Example: Force New Build​

Example: Build Source with a Worker Command​

Example: Rebuild from Previous Version​

Example Response​

Redeploy​

Request Body​

Example: Redeploy Current Version​

Example: Redeploy Specific Version​

Example Response​

Use Cases​

Rollback​

Request Body​

Example: Rollback to Previous Version​

Example: Rollback to Specific Version​

Example Response​

Notes​

Stop Environment​

Request Body​

Example​

Example Response​

Notes​

Start Environment​

Request Body​

Example​

Example Response​

Notes​

Error Responses​

Deploy Image

Request Body

Example

Example Response

Notes

Startup Configuration

Trigger Build

Request Body

Example: Trigger New Build

Example: Force New Build

Example: Build Source with a Worker Command

Example: Rebuild from Previous Version

Example Response

Redeploy

Request Body

Example: Redeploy Current Version

Example: Redeploy Specific Version

Example Response

Use Cases

Rollback

Request Body

Example: Rollback to Previous Version

Example: Rollback to Specific Version

Example Response

Notes

Stop Environment

Request Body

Example

Example Response

Notes

Start Environment

Request Body

Example

Example Response

Notes

Error Responses