Skip to main content
The Astro API is available in Generally Available (GA), Labs, and beta versions. GA versions provide stable, production-ready contracts for long-term integrations. Labs versions are experimental and can change in breaking ways.

​
Available versions

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

​
v1labs

The v1labs API is the channel for experimental, preview-stage endpoints. It uses the same authentication as v1, but it runs at a separate base URL and follows its own release lifecycle:
An endpoint stays in v1labs until it is stable enough for v1. Astronomer can change or remove a v1labs endpoint at any time, so v1labs isn’t a good fit for production integrations. For what the Labs stage means for stability, support, and SLAs, see Astronomer feature lifecycle. v1labs uses the same major.minor strategy as v1, with two differences:
  • You pin a minor version with the X-Labs-API-Version header instead of X-API-Version.
  • You download the specification from https://api.astronomer.io/spec/labs/v1 for the latest minor version, or from a specific version endpoint such as https://api.astronomer.io/spec/labs/v1.0.
For authentication, error responses, and a worked pinning example, see the Astro v1 Labs API overview. For the endpoints v1labs adds and changes, see the v1labs changelog.