App Environment Status API

The App Environment Status API allows you to get the current runtime status and health of an app environment in Quave ONE.

Make sure to read the Get Started document to understand how the API works.

Note: This API endpoint accepts only user tokens (not environment tokens).

Get App Environment Status

To retrieve the status for an app environment, send a GET request to the /api/public/v1/app-env/status endpoint. You need to provide either appEnvId or envName to identify the environment.

Required Parameters (Either/Or)

You must provide either appEnvId or envName:

Parameter	Type	Description
`appEnvId`	String	The ID of the app environment to retrieve status for.
`envName`	String	The CLI environment name (alternative to appEnvId).

Response Structure

The response is a JSON object with the following fields:

Field	Type	Description
`appEnvId`	String	The app environment ID.
`activityStatus`	String	Current environment process status: `STOPPED`, `PENDING`, `UPDATING`, `RUNNING`.
`activityStatusLabel`	String	Human-readable environment process status label.
`currentContentId`	String	ID of the currently deployed content version (null if not deployed).
`currentVersion`	Number	Version number of the current deployment (null if not deployed).
`currentDeployment`	Object	Details of the currently active content version (see below).
`latestContentId`	String	ID of the newest content version, including a source build that is not current yet.
`latestVersion`	Number	Version number of the newest content version.
`latestDeployment`	Object	Details of the newest content lifecycle, including build-stage statuses.
`pendingChanges`	Object	Pending configuration changes (see below).
`hosts`	Array	Array of host configurations (see below).

Deployment Objects

The currentDeployment and latestDeployment objects use the same shape. currentDeployment describes the content version currently attached to the environment. latestDeployment describes the newest content version lifecycle, so it can show source-build statuses such as BUILDING before that version becomes current.

Each deployment object contains:

Field	Type	Description
`contentId`	String	Content version ID.
`uploadEventId`	String	CLI source upload event ID when this content came from a CLI source deploy; otherwise `null`.
`version`	Number	Version number.
`status`	String	Deployment status (e.g., `DEPLOYED`, `DEPLOYING`, `FAILED`).
`statusLabel`	String	Human-readable status label.
`isFailed`	Boolean	Whether this content lifecycle is in a failed status.
`isSuccess`	Boolean	Whether this content lifecycle is in a successful status.
`isInProgress`	Boolean	Whether this content lifecycle is still building, deploying, scaling, or stopping.
`deployedAt`	Date	Timestamp when this content version was created or started.
`gitBranch`	String	Git branch name (null for CLI deployments).
`gitCommitId`	String	Git commit SHA (null for CLI deployments).
`containerImage`	Object	Docker image reference, including namespace, repository, and tag when available.
`type`	String	Deployment type: `BUILD` or `IMAGE_FROM`.

Pending Changes Object

The pendingChanges object indicates whether there are configuration changes waiting to be applied:

Field	Type	Description
`hasBuildChanges`	Boolean	Whether there are pending build configuration changes.
`hasDeployChanges`	Boolean	Whether there are pending deployment configuration changes.
`hasScaleChanges`	Boolean	Whether there are pending scaling configuration changes.

Host Object

Each host in the hosts array contains:

Field	Type	Description
`host`	String	Domain name (e.g., "app.example.com").
`status`	String	Host status (e.g., `ACTIVE`, `PENDING`).
`useSSL`	Boolean	Whether SSL/TLS is enabled for this host.
`isInternal`	Boolean	Whether this is an internal-only host.

Example: Basic Status Retrieval (with appEnvId)

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/status?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b'

Example: Basic Status Retrieval (with envName)

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/status?envName=production'

Example Response

{
  "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
  "activityStatus": "RUNNING",
  "activityStatusLabel": "Running",
  "currentContentId": "abc123def456",
  "currentVersion": 42,
  "currentDeployment": {
    "contentId": "abc123def456",
    "uploadEventId": null,
    "version": 42,
    "status": "DEPLOYED",
    "statusLabel": "Deployed",
    "isFailed": false,
    "isSuccess": true,
    "isInProgress": false,
    "deployedAt": "2024-01-15T10:30:00.000Z",
    "gitBranch": "main",
    "gitCommitId": "a1b2c3d4e5f6",
    "containerImage": {
      "namespace": "registry.example.com",
      "repo": "app",
      "tag": "v42"
    },
    "type": "BUILD"
  },
  "latestContentId": "def456ghi789",
  "latestVersion": 43,
  "latestDeployment": {
    "contentId": "def456ghi789",
    "uploadEventId": "upload-event-43",
    "version": 43,
    "status": "BUILDING",
    "statusLabel": "Building",
    "isFailed": false,
    "isSuccess": false,
    "isInProgress": true,
    "deployedAt": "2024-01-15T10:35:00.000Z",
    "gitBranch": "main",
    "gitCommitId": "b2c3d4e5f6a7",
    "containerImage": {
      "namespace": "registry.example.com",
      "repo": "app",
      "tag": "v43"
    },
    "type": "BUILD"
  },
  "pendingChanges": {
    "hasBuildChanges": false,
    "hasDeployChanges": true,
    "hasScaleChanges": false
  },
  "hosts": [
    {
      "host": "app.example.com",
      "status": "ACTIVE",
      "useSSL": true,
      "isInternal": false
    },
    {
      "host": "internal.app.local",
      "status": "ACTIVE",
      "useSSL": false,
      "isInternal": true
    }
  ]
}

Environment Status Values

The activityStatus field can have the following values:

STOPPED - Environment is not running
PENDING - Initial state, not yet deployed
UPDATING - Changes in progress (building, deploying, or scaling)
RUNNING - Stable and operational

Use Cases

This endpoint is useful for:

Health Checks - Determine if your app is running or experiencing issues
Deployment Status - Check the currently deployed version and the newest build/deploy activity
Change Detection - See if there are pending configuration changes
Monitoring - Integrate with monitoring tools to track app status

Error Responses

400 - Missing required parameters (neither appEnvId nor envName provided)
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

Notes

Environment Identification:

You can use either appEnvId or envName to identify the environment
If both are provided, appEnvId takes precedence
When using envName, the endpoint will look up the corresponding appEnvId

Status Interpretation:

If currentContentId is null, the environment has never had a current content version
latestDeployment can be present even when currentContentId is null or still points to the previous version, for example during a source build
uploadEventId is intended for CLI source deploy correlation and is null for older contents or non-CLI source uploads
UPDATING status indicates an active deployment, scaling, or build operation
pendingChanges shows changes that will be applied on the next deployment

Get App Environment Status​

Required Parameters (Either/Or)​

Response Structure​

Deployment Objects​

Pending Changes Object​

Host Object​

Example: Basic Status Retrieval (with appEnvId)​

Example: Basic Status Retrieval (with envName)​

Example Response​

Environment Status Values​

Use Cases​

Error Responses​

Notes​