Astro API versioning, maintenance, and support

Learn how Astronomer versions and maintains the Astro API.

The Astro API is available in both Generally Available (GA) and beta versions. GA versions provide stable, production-ready contracts for long-term integrations.

Available versions

Version	Status	Base URL	Release Date	End of Support
v1	GA	https://api.astronomer.io/v1/	January 28, 2026	Active
v1beta1	Deprecated	https://api.astronomer.io/iam/v1beta1/ https://api.astronomer.io/platform/v1beta1/	April 2024	January 2027

v1beta1 users have a 12-month migration window to transition to v1. See the v1 migration guide for key changes and migration steps.

Version upgrades and breaking changes

The Astro API uses a major.minor versioning strategy to provide stability while allowing for continuous improvement.

Versioning approach

Major version

The API major version is indicated in the URI path. For example, v1 APIs use the base URL:

https://api.astronomer.io/v1/

Breaking changes require a new major version with a dedicated migration guide and deprecation timeline.

Minor version

You can pin to a specific minor version using the X-API-Version header:

curl --location 'https://api.astronomer.io/v1/organizations/<org-id>/clusters' \
--header 'Authorization: Bearer <your-api-token>' \
--header 'X-API-Version: 1.0'

If you don’t specify the X-API-Version header, your requests automatically use the latest minor version within the major version. This ensures you receive non-breaking improvements and new features automatically.

OpenAPI specification

You can download the v1 OpenAPI specification for the Astro API from:

• Latest minor version: https://api.astronomer.io/spec/v1
• Specific version: https://api.astronomer.io/spec/v1.0

The /spec/v1 endpoint always returns the latest minor version within the v1 major release, while specific version endpoints like /spec/v1.0 return that exact specification.