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

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.
status	String	Current environment status: STOPPED, PENDING, UPDATING, RUNNING.
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 current deployment (see below).
pendingChanges	Object	Pending configuration changes (see below).
hosts	Array	Array of host configurations (see below).

Current Deployment Object

The currentDeployment object contains:

Field	Type	Description
contentId	String	Content version ID.
version	Number	Version number.
status	String	Deployment status (e.g., DEPLOYED, DEPLOYING, FAILED).
deployedAt	Date	Timestamp when this version was deployed.
gitBranch	String	Git branch name (null for CLI deployments).
gitCommitId	String	Git commit SHA (null for CLI deployments).
containerImage	String	Docker image reference.
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",
  "status": "RUNNING",
  "currentContentId": "abc123def456",
  "currentVersion": 42,
  "currentDeployment": {
    "contentId": "abc123def456",
    "version": 42,
    "status": "DEPLOYED",
    "deployedAt": "2024-01-15T10:30:00.000Z",
    "gitBranch": "main",
    "gitCommitId": "a1b2c3d4e5f6",
    "containerImage": "registry.example.com/app:v42",
    "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 status 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:

1. Health Checks - Determine if your app is running or experiencing issues
2. Deployment Status - Check the currently deployed version and commit
3. Change Detection - See if there are pending configuration changes
4. 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 been deployed
• UPDATING status indicates an active deployment, scaling, or build operation
• pendingChanges shows changes that will be applied on the next deployment