Migrate to v1

This guide helps you migrate from the Astro API v1beta1 to v1. The v1 API consolidates the previously separate IAM and Platform APIs into a single endpoint with improved stability and support.

Key changes

API consolidation

The two separate v1beta1 APIs are now unified:

Before (v1beta1):

• IAM API: https://api.astronomer.io/iam/v1beta1/
• Platform API: https://api.astronomer.io/platform/v1beta1/

After (v1):

• Unified API: https://api.astronomer.io/v1/

Unsupported endpoints

The following endpoints are currently not supported in v1:

• Alert endpoints:

  • POST /organizations/{organizationId}/alerts
  • GET /organizations/{organizationId}/alerts
  • GET /organizations/{organizationId}/alerts/{alertId}
  • POST /organizations/{organizationId}/alerts/{alertId}
  • DELETE /organizations/{organizationId}/alerts/{alertId}

• Notification channel endpoints:

  • POST /organizations/{organizationId}/notification-channels
  • GET /organizations/{organizationId}/notification-channels
  • GET /organizations/{organizationId}/notification-channels/{notificationChannelId}
  • POST /organizations/{organizationId}/notification-channels/{notificationChannelId}
  • DELETE /organizations/{organizationId}/notification-channels/{notificationChannelId}

If your integration relies on these endpoints, contact Astronomer Support for guidance on alternative approaches.

Migration steps

Step 1: Update base URLs

Update all API calls to use the new v1 base URL:

1
- const IAM_BASE_URL = 'https://api.astronomer.io/iam/v1beta1';
2
- const PLATFORM_BASE_URL = 'https://api.astronomer.io/platform/v1beta1';
3
+ const BASE_URL = 'https://api.astronomer.io/v1';

Step 2: Update endpoint paths

All endpoints that previously used the IAM or Platform base URLs now use the unified v1 base URL:

Example: List users

1
- GET https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/users
2
+ GET https://api.astronomer.io/v1/organizations/{organizationId}/users

Example: List deployments

1
- GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments
2
+ GET https://api.astronomer.io/v1/organizations/{organizationId}/deployments

Step 3: Update alert and notification channel logic

Alert and notification channel APIs currently are not supported in v1. If your integration uses these endpoints, you’ll need to update your workflows:

1
- // Create an alert
2
- const response = await fetch(
3
-   `${PLATFORM_BASE_URL}/organizations/${orgId}/alerts`,
4
-   {
5
-     method: 'POST',
6
-     headers: { 'Authorization': `Bearer ${token}` },
7
-     body: JSON.stringify(alertConfig)
8
-   }
9
- );
10
+ // Alert APIs are currently not supported in v1
11
+ // Contact Astronomer Support for alternative approaches

Step 4: Test your integration

Before fully migrating to production:

1. Update your development/staging environment to use v1 endpoints
2. Test all API calls to ensure they work as expected
3. Verify authentication still works with the new base URL
4. Check error handling for any changes in response formats
5. Monitor for any unexpected behavior

Step 5: Update production

After testing is complete, update your production environment to use the v1 API.

Examples

v1beta1

1
# Before (v1beta1)
2
iam_base_url = "https://api.astronomer.io/iam/v1beta1"
3
platform_base_url = "https://api.astronomer.io/platform/v1beta1"
4
5
# List users
6
response = requests.get(
7
    f"{iam_base_url}/organizations/{org_id}/users",
8
    headers={"Authorization": f"Bearer {token}"}
9
)
10
11
# List deployments
12
response = requests.get(
13
    f"{platform_base_url}/organizations/{org_id}/deployments",
14
    headers={"Authorization": f"Bearer {token}"}
15
)

v1

1
# After (v1)
2
base_url = "https://api.astronomer.io/v1"
3
4
# List users
5
response = requests.get(
6
    f"{base_url}/organizations/{org_id}/users",
7
    headers={"Authorization": f"Bearer {token}"}
8
)
9
10
# List deployments
11
response = requests.get(
12
    f"{base_url}/organizations/{org_id}/deployments",
13
    headers={"Authorization": f"Bearer {token}"}
14
)

If you have questions or need assistance migrating to v1, reach out to Astronomer Support.