App Environment Region API

The App Environment Region API allows you to change the region of app environments in Quave Cloud. Changing regions is a complex operation that requires proper DNS (CNAME) configuration.

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.

Overview

Changing an app environment's region is a disruptive operation - the environment will be unreachable for approximately 2 minutes during the migration. Before changing regions, you must ensure your custom hosts have CNAME records pointing to the correct ingress URL.

Two-Phase Approach

1. Check CNAME Records - Verify your DNS is properly configured
2. Change Region - Execute the region change (validates CNAME internally)

---

Check CNAME Records

Checks if CNAME records are properly configured for region change. All custom hosts must have CNAME records pointing to the ingress URL before changing regions.

Endpoint: GET /api/public/v1/app-env/check-cname

Query Parameters

Parameter	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 GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/check-cname?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b'

Example Response (Valid)

{
  "valid": true,
  "targetCname": "my-app-production.zcloud.ws",
  "customHosts": ["api.example.com", "www.example.com"],
  "message": "All CNAME records are valid. Region change is allowed."
}

Example Response (Invalid)

{
  "valid": false,
  "targetCname": "my-app-production.zcloud.ws",
  "customHosts": ["api.example.com", "www.example.com"],
  "message": "Custom host 'api.example.com' does not have a CNAME record pointing to 'my-app-production.zcloud.ws'. Create the CNAME record before changing regions."
}

Example Response (No Custom Hosts)

{
  "valid": true,
  "customHosts": [],
  "message": "No custom hosts configured. Region change is allowed."
}

Response Fields

Field	Type	Description
valid	Boolean	Whether all CNAME records are properly configured.
targetCname	String	The CNAME target that custom hosts should point to.
customHosts	Array	List of custom hostnames configured for this environment.
message	String	Human-readable explanation of the result.

Why CNAME Validation?

When you change regions, the ingress URL changes (each region has its own ingress). If your custom hosts use A records (direct IP addresses), they won't automatically route to the new region's IP. CNAME records allow seamless region migration because they point to a domain name that we update automatically.

---

Change Region

Changes the region of an app environment. This operation validates CNAME records internally before proceeding.

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

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).
region	String	Yes	The target region value (e.g., "us-5", "eu-1").

Example

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

Example Response

{
  "success": true,
  "message": "Environment region changed from 'eu-1' to 'us-5'. A deployment to the new region has been triggered.",
  "oldRegion": "eu-1",
  "newRegion": "us-5",
  "appEnv": {
    "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
    "name": "Production",
    "region": "us-5",
    "isChangingRegion": true
  }
}

What Happens During Region Change

1. Validation - Verifies CNAME records, region availability, and that no region change is already in progress
2. Destroy Old Environment - Infrastructure in the old region is torn down
3. Update Hosts - Auto-generated hosts are regenerated for the new region; custom hosts are preserved
4. Update CNAME - Route53 CNAME record is updated to point to the new region's ingress
5. Create Monitoring - Grafana setup is created in the new region
6. Deploy - Current deployment is redeployed in the new region
7. Flag Cleared - isChangingRegion flag is cleared when deployment completes

Validations

The API validates the following before proceeding:

Validation	Error Message
CNAME records valid	Custom host does not have a CNAME record pointing to the ingress
Region exists	Region does not exist
Region enabled	Region is not enabled for this account. Contact support.
Different region	Environment is already in this region
No change in progress	A region change is already in progress. Wait for it to complete.

Notes

• Disruptive Operation: The environment will be unreachable for ~2 minutes during migration.
• No applyImmediately: Region change is always immediate - there's no pending changes workflow.
• Data Migration: This only moves the application infrastructure. Database/storage data may need separate migration.
• Custom Hosts Preserved: Your custom hostnames are kept; only auto-generated hosts are regenerated.
• isChangingRegion Flag: This flag is set during the operation and automatically cleared when deployment completes. The UI shows a progress indicator while this flag is true.

---

Available Regions

To see which regions are available for your account, check the region selector in the Quave Cloud dashboard or use the List App Environments endpoint which includes region information.

Common regions include:

• us-5 - United States
• eu-1 - Europe

Some regions may require enablement by the Quave Cloud team. Contact support if you need access to additional regions.

---

Error Responses

All endpoints may return the following error responses:

Status	Description
400	Invalid request (validation failed, see error message).
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.