> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

<Update label="2026-07-16">
  ## Summary

  * Added an optional `fieldErrors` array to the `Error` response schema. Request-validation failures (`400` responses) now include one entry per failed field, with a machine-readable code alongside the existing human-readable `message`.

  ## Added

  * **Properties**
    * `fieldErrors` (array of `FieldValidationError`): added to `Error`. Only present on `400` responses caused by request binding or validation. Each entry names the field, a validator code (for example `required`, `max`, `oneof`), and a friendly message.
  * **Schemas**
    * `FieldValidationError`: new schema with required `field`, `code`, and `message` string properties. Represents a single failed validation constraint.
</Update>

<Update label="2026-07-01">
  ## Summary

  * Added `setFields` to `EnvironmentObject` and `EnvironmentObjectLink` responses, and `unsetFields` to environment object link update overrides. Together they let clients distinguish a set-but-masked secret from an unset field, and clear a link override so it falls back to its parent value.
  * Changed the permission required to update Team roles from the org-wide `organization.teams.update` to `organization.teamRoles.access`. This fixes a regression where callers with only deployment-scoped team permissions received `403` errors when assigning a Team to a Deployment.

  ## Added

  * **Properties**
    * `setFields` (array of strings, required): added to `EnvironmentObject` and `EnvironmentObjectLink`. Names the value and override fields that currently hold a value, including masked secrets. Map members are reported as dotted paths (for example `extra.aws_secret`).
    * `unsetFields` (array of strings, maximum 100 items): added to `UpdateEnvironmentObjectOverridesRequest`. Names override fields to unset on a link so it inherits the parent value. A field can't be both set and listed in `unsetFields` in the same request.

  ## Changed

  * `POST /organizations/{organizationId}/teams/{teamId}/roles` (`UpdateTeamRoles`) now requires the `organization.teamRoles.access` permission instead of `organization.teams.update`. Individual role changes in the request are still authorized against their own scope (organization, workspace, or deployment).
</Update>

<Update label="2026-06-25">
  ## Summary

  * Added Private Network Egress mode for AWS clusters. When enabled, this mode disables public Internet connectivity from the cluster's Deployments and metrics exports. Cluster create, update, and read schemas gain an `isPrivateNetworkEgressEnabled` field.
  * Added a `description` field to environment objects. Environment object create, update, and read schemas now accept and return an optional description of up to 500 characters.

  ## Added

  * **Properties**
    * `isPrivateNetworkEgressEnabled` (boolean, AWS clusters only): added to `Cluster`, `CreateAwsClusterRequest`, and `UpdateDedicatedClusterRequest`. When true, disables public Internet connectivity from the cluster's Deployments and metrics exports.
    * `description` (string): added to `CreateEnvironmentObjectRequest` and `UpdateEnvironmentObjectRequest` (maximum 500 characters), and to `EnvironmentObject`.
</Update>

<Update label="2026-06-17">
  ## Summary

  * Added `hasAiFeaturesDisabled` and a required `isBlockedEnableAiFeatures` to the `Organization` schema. `hasAiFeaturesDisabled` indicates whether AI features are disabled for the Organization, and `isBlockedEnableAiFeatures` indicates whether the Organization is blocked from enabling AI features.
  * Added `hasAiFeaturesDisabled` to `UpdateOrganizationRequest` so callers can set whether AI features are disabled when updating an Organization.

  ## Added

  * **Properties**
    * `Organization`: `hasAiFeaturesDisabled` (boolean). Whether AI features are disabled for the Organization.
    * `Organization`: `isBlockedEnableAiFeatures` (boolean, required). Whether the Organization is blocked from enabling AI features.
    * `UpdateOrganizationRequest`: `hasAiFeaturesDisabled` (boolean). Whether AI features are disabled for the Organization.
</Update>

<Update label="2026-06-11">
  ## Summary

  * Added environment variable support to environment objects. A new `ENVIRONMENT_VARIABLE` object type lets you create, update, and read environment variables managed by the Astro Environment Manager, with an optional secret value.
  * Added SigV4 authentication for metrics export environment objects. A new `SIGV4` auth type accepts an `sigV4AssumeArn` IAM role ARN and an `sigV4StsRegion` AWS STS region.
  * Added Disaster Recovery (DR) support for GCP clusters. Cluster create, update, and read schemas gain `drPodSubnetRange`, `drServiceSubnetRange`, and `drServicePeeringRange`, and the existing DR fields are no longer scoped to AWS only.
  * Added a `location` field to `ProviderRegion` for multi-region DR compatibility.

  ## Added

  * **Enum values**
    * `ENVIRONMENT_VARIABLE`: added to the environment object `type` enum on `CreateEnvironmentObjectRequest` and `EnvironmentObject`, and to the `type` query parameter on `GET /organizations/{organizationId}/environment-objects`.
    * `SIGV4`: added to the `authType` enum on the six metrics export schemas (`CreateEnvironmentObjectMetricsExportRequest`, `CreateEnvironmentObjectMetricsExportOverridesRequest`, `UpdateEnvironmentObjectMetricsExportRequest`, `UpdateEnvironmentObjectMetricsExportOverridesRequest`, `EnvironmentObjectMetricsExport`, and `EnvironmentObjectMetricsExportOverrides`).
  * **Schemas**
    * `CreateEnvironmentObjectEnvironmentVariableRequest`: `isSecret` (boolean) and `value` (string).
    * `CreateEnvironmentObjectEnvironmentVariableOverridesRequest`: `value` (string).
    * `UpdateEnvironmentObjectEnvironmentVariableRequest`: `value` (string).
    * `UpdateEnvironmentObjectEnvironmentVariableOverridesRequest`: `value` (string).
    * `EnvironmentObjectEnvironmentVariable`: `isSecret` (boolean, required) and `value` (string, required). `value` is returned empty when the variable is a secret.
    * `EnvironmentObjectEnvironmentVariableOverrides`: `value` (string, required).
  * **Properties**
    * `environmentVariable`: added to `CreateEnvironmentObjectRequest`, `CreateEnvironmentObjectOverridesRequest`, `UpdateEnvironmentObjectRequest`, `UpdateEnvironmentObjectOverridesRequest`, and `EnvironmentObject`.
    * `environmentVariableOverrides`: added to `EnvironmentObjectLink`.
    * `sigV4AssumeArn` (string) and `sigV4StsRegion` (string): added to all six metrics export schemas listed under **Enum values**.
    * `drPodSubnetRange`, `drServiceSubnetRange`, and `drServicePeeringRange` (string, GCP clusters only): added to `Cluster`, `CreateGcpClusterRequest`, and `UpdateDedicatedClusterRequest`.
    * `enableReplicationTimeControl` (boolean): added to `CreateAzureClusterRequest`, `CreateGcpClusterRequest`, and `UpdateDedicatedClusterRequest`.
    * `drRegion` and `drVpcSubnetRange`: added to `UpdateDedicatedClusterRequest`.
    * `location` (string): added to `ProviderRegion`. The multi-region location code for DR compatibility.

  ## Changed

  * `enableReplicationTimeControl` description updated from "S3 Replication Time Control" to "Bucket Storage Replication Time Control" on `Cluster` and `CreateAwsClusterRequest`.
  * `drRegion` is no longer AWS-only: removed "For AWS clusters only" on `CreateAwsClusterRequest`, `CreateAzureClusterRequest`, and `CreateGcpClusterRequest`.
  * `drVpcSubnetRange` is no longer AWS-only: removed "For AWS clusters only" on `Cluster`, `CreateAwsClusterRequest`, `CreateAzureClusterRequest`, and `CreateGcpClusterRequest`.
  * `drSecondaryVpcCidr` description now notes it applies to AWS clusters only on `CreateAwsClusterRequest`.
  * `POST /organizations/{organizationId}/environment-objects` (CreateEnvironmentObject) description updated to include environment variables alongside connections, Airflow variables, and metrics export resources.
</Update>

<Update label="2026-06-10">
  ## Summary

  * Added two endpoints for managing allowed IP address ranges in bulk: `POST /organizations/{organizationId}/allowed-ip-address-ranges/bulk-create` and `POST /organizations/{organizationId}/allowed-ip-address-ranges/bulk-delete`. Each request accepts up to 1,000 items and processes the batch atomically.

  ## Added

  * **Endpoints**
    * `POST /organizations/{organizationId}/allowed-ip-address-ranges/bulk-create`: Create up to 1,000 allowed IP address ranges for an Organization in one request. The batch is created atomically: if any value fails validation or conflicts with an existing range, no ranges are created. The endpoint is not idempotent, so a retry after an unacknowledged 2xx response can return `409`. On success, the endpoint returns the created ranges as an `AllowedIpAddressRangesList`. Requires the `organization.allowedIpAddressRanges.create` permission.
    * `POST /organizations/{organizationId}/allowed-ip-address-ranges/bulk-delete`: Delete up to 1,000 allowed IP address ranges for an Organization in one request. The batch is deleted atomically. Unknown and duplicate IDs are accepted and ignored, and matching ranges for the Organization are deleted. The endpoint returns `204` with no response body. Requires the `organization.allowedIpAddressRanges.delete` permission.

  * **Schemas**
    * `BulkCreateAllowedIpAddressRangesRequest`: Request body for bulk create. Required: `allowedIpAddressRanges`, a non-empty array of up to 1,000 CIDR-format strings.
    * `BulkDeleteAllowedIpAddressRangesRequest`: Request body for bulk delete. Required: `allowedIpAddressRangeIds`, a non-empty array of up to 1,000 allowed IP address range IDs.
    * `AllowedIpAddressRangesList`: Response body for bulk create. Required: `allowedIpAddressRanges`, an array of `AllowedIpAddressRange`.
</Update>

<Update label="2026-06-04">
  ## Summary

  * Added `podEphemeralStorage` to the worker queue schemas so callers can set the ephemeral storage limit for each worker Pod.

  ## Added

  * **Properties**
    * `WorkerQueue`: `podEphemeralStorage` (string). The ephemeral storage limit for each worker Pod. Units are in Gibibytes or `Gi`. Example: `10Gi`.
    * `WorkerQueueRequest`: `podEphemeralStorage` (string). The ephemeral storage limit for each worker Pod. Must be a valid Kubernetes resource string, for example `10Gi`.
    * `UpdateWorkerQueueRequest`: `podEphemeralStorage` (string). The ephemeral storage limit for each worker Pod. Must be a valid Kubernetes resource string, for example `10Gi`.
</Update>

<Update label="2026-05-20">
  ## Summary

  * Added `lastRotatedAt` to `ApiToken` so callers can see when a token was last rotated.
  * Added a new `git` object (`CreateDeployGitRequest` on requests, `DeployGit` on responses) on `CreateDeployRequest` and `Deploy` for attaching git commit metadata to a deploy. A new `GENERIC` provider value (alongside `GITHUB`) supports non-GitHub remotes such as GitLab, Bitbucket, and self-hosted git via a `remoteUrl` field.
  * Added `IBM_ENTERPRISE` as a value on `OrganizationProductPlan.productPlanName`.
  * Narrowed `Workspace.defaultCloudProvider` from a free-form string to the enum `AWS`, `AZURE`, `GCP`.

  ## Added

  * **Schemas**
    * `CreateDeployGitRequest` and `DeployGit`: Git commit metadata associated with a deploy. Required: `commitSha`, `provider`. Optional: `account`, `authorName`, `authorUrl`, `authorUsername`, `beforeCommitSha`, `branch`, `commitUrl`, `path`, `remoteUrl`, `repo`. `provider` accepts `GITHUB` or `GENERIC`. For `GITHUB`, supply `account` and `repo` and leave `remoteUrl` empty. For `GENERIC`, supply `remoteUrl` and leave `account` and `repo` empty.

  * **Properties**
    * `ApiToken`: `lastRotatedAt` (string, date-time). The time when the API token was last rotated.
    * `CreateDeployRequest`, `Deploy`: `git` (object). Git commit metadata for the deploy. See `CreateDeployGitRequest` and `DeployGit`.

  * **Enum values**
    * `OrganizationProductPlan.productPlanName`: `IBM_ENTERPRISE`.

  ## Changed

  * **Schemas**
    * `Workspace.defaultCloudProvider`: Now restricted to the enum `AWS`, `AZURE`, `GCP` (previously a free-form string).
</Update>

<Update label="2026-04-22">
  ## Summary

  * Create Deployment requests now require only `name` and `workspaceId`. The server resolves infrastructure from Workspace defaults (or auto-selects when the Organization has a single non-shared cluster), infers the Deployment `type` from the resolved cluster, and applies defaults for runtime version, executor, scheduler size, and related fields. This reduces the create Deployment API from roughly 15 required fields down to 2.
  * Added `defaultClusterId`, `defaultCloudProvider`, and `defaultRegion` on `Workspace` so Workspace admins can pre-configure target infrastructure for new Deployments. `defaultClusterId` is mutually exclusive with `defaultCloudProvider` and `defaultRegion`.
  * Added `GET /organizations/{organizationId}/deployments/{deploymentId}/logs` and `GET /users/self` endpoints.
  * Added `hasAllowedIpAddressRanges` and `shouldEnforceDedicatedClusters` as required properties on the `Organization` schema.
  * Added `workspaceId` and `deploymentId` filters to `GET /organizations/{organizationId}/teams`.

  ## Added

  * **Endpoints**
    * `GET /organizations/{organizationId}/deployments/{deploymentId}/logs`: Get logs for an Astro Deployment. Supports filtering by log source (`scheduler`, `triggerer`, `worker`, `webserver`, `dag-processor`, `apiserver`), time range, text search, and pagination.
    * `GET /users/self`: Get the authenticated user's profile, roles, invites, and feature flags. Supports an optional `createIfNotExist` query parameter.

  * **Schemas**
    * `CreateDeploymentInstanceSpecRequest`
      * `au`: Integer. Astro unit allocation for the Deployment pod. Minimum `5`, maximum `24`. Optional.
      * `replicas`: Integer. Number of pod replicas. Minimum `1`, maximum `4`. Optional.
    * `UpdateDeploymentInstanceSpecRequest`
      * `au`: Integer. Astro unit allocation for the Deployment pod. Minimum `5`, maximum `24`. Required.
      * `replicas`: Integer. Number of pod replicas. Minimum `1`, maximum `4`. Required.
    * `DeploymentLog`
      * Required: `limit`, `maxNumResults`, `offset`, `resultCount`, `results`, `searchId`.
      * `results`: Array of `DeploymentLogEntry`.
    * `DeploymentLogEntry`
      * Required: `raw` (string), `source` (enum: `scheduler`, `webserver`, `triggerer`, `worker`, `dag-processor`, `apiserver`), `timestamp` (number).
    * `SelfUser`
      * Required: `avatarUrl`, `createdAt`, `fullName`, `id`, `status`, `updatedAt`, `username`.
      * Also includes `featureFlags`, `invites`, `isIdpManaged`, `organizationId`, and `roles`.
    * `SelfUserFeatureFlag`, `SelfUserInvite`, `SelfUserRole`, `SelfUserRoleScope`: Supporting schemas for `SelfUser`.
    * `UpdateWorkerQueueRequest`: Used by the `workerQueues` array on `UpdateDedicatedDeploymentRequest`, `UpdateHybridDeploymentRequest`, and `UpdateStandardDeploymentRequest`. Required fields: `isDefault`, `maxWorkerCount`, `minWorkerCount`, `name`, `workerConcurrency`.

  * **Properties**
    * `CreateWorkspaceRequest` and `UpdateWorkspaceRequest`: `defaultCloudProvider` (enum: `AWS`, `AZURE`, `GCP`), `defaultClusterId`, and `defaultRegion`. Workspace admins use these fields to pre-configure target infrastructure for new Deployments. When a create Deployment request omits `clusterId`, `cloudProvider`, and `region`, the server uses these Workspace defaults. `defaultClusterId` is mutually exclusive with `defaultCloudProvider` and `defaultRegion`.
    * `Organization`: `hasAllowedIpAddressRanges` (boolean, required) indicating whether the Organization has at least one allowed IP address range configured, and `shouldEnforceDedicatedClusters` (boolean, required).
    * `UpdateOrganizationRequest`: `shouldEnforceDedicatedClusters` (boolean).
    * `Workspace`: `defaultCloudProvider`, `defaultClusterId`, and `defaultRegion` (strings) reflecting the configured defaults.

  * **Query parameters**
    * `GET /organizations/{organizationId}/teams`: `workspaceId` and `deploymentId` filter the response to Teams with a role in the specified Workspace or Deployment.

  ## Changed

  * **Removed required fields on create Deployment requests.** When a field is omitted, the server applies a default. The only remaining required fields are `name` and `workspaceId`.
</Update>

<Update label="2026-04-02">
  ## Summary

  * Added new schemas for `UserTeamMembership` and `UserTeamsPaginated` to manage team memberships and pagination.
  * Enhanced `Cluster` schema with new properties for Disaster Recovery (DR) support, including `drRegion`, `isDrEnabled`, and others.
  * Introduced new permissions for managing environment objects and API tokens within organizations.
  * Removed `astroRuntimeVersion` property from deployment update requests.
  * Updated sorting options and descriptions for listing user teams within an organization.

  ## Added

  * **Schemas:**
    * `UserTeamMembership`
      * `dagRoles`: Array of DAG roles.
      * `deploymentRoles`: Array of deployment roles.
      * `description`: String, example: 'My Team description'.
      * `id`: String, example: 'clma5ftgk000008mhgev00k7d'.
      * `isIdpManaged`: Boolean, example: False.
      * `name`: String, example: 'My Team'.
      * `organizationRole`: Enum with values like '`ORGANIZATION_OWNER`', '`ORGANIZATION_MEMBER`', etc.
      * `rolesCount`: Integer, example: 1.
      * `workspaceRoles`: Array of workspace roles.
    * `UserTeamsPaginated`
      * `limit`: Integer, example: 10.
      * `offset`: Integer, example: 0.
      * `teams`: Array of `UserTeamMembership`.
      * `totalCount`: Integer, example: 100.
    * `Cluster`
      * `drRegion`: String, example: 'us-east-1'.
      * `drSecondaryVpcCidr`: String.
      * `drVpcSubnetRange`: String.
      * `enableReplicationTimeControl`: Boolean.
      * `failoverInProgress`: Boolean.
      * `isDrEnabled`: Boolean.
      * `isFailedOver`: Boolean.
    * `CreateAwsClusterRequest`, `CreateAzureClusterRequest`, `CreateGcpClusterRequest`
      * `drRegion`: String, example: 'us-west-2'.
      * `drSecondaryVpcCidr`: String, example: '100.64.0.0/19'.
      * `drVpcSubnetRange`: String, example: '172.20.0.0/22'.
      * `enableReplicationTimeControl`: Boolean.
    * `CreateDedicatedDeploymentRequest`, `CreateHybridDeploymentRequest`, `CreateStandardDeploymentRequest`
      * `drWorkloadIdentity`: String, example: 'arn:aws:iam::123456789:role/AirflowS3Logs-clmk2qqia000008mhff3ndjr0'.
    * `Deployment`
      * `drExternalIPs`: Array of strings.
      * `drOidcIssuerUrl`: String, example: 'https\://`westus2.oic.prod`-aks.azure.com/...'.
      * `effectiveDRWorkloadIdentity`: String.
    * `UpdateDedicatedClusterRequest`
      * `enableDr`: Boolean.
      * `isFailedOver`: Boolean.
    * `UpdateDedicatedDeploymentRequest`, `UpdateHybridDeploymentRequest`, `UpdateStandardDeploymentRequest`
      * `drWorkloadIdentity`: String.
      * `environmentVariables`: List of environment variables.

  * **Permissions:**
    * `/organizations/{organizationId}/environment-objects` and related endpoints: `organization.envObjects.access`.
    * `/organizations/{organizationId}/tokens` and related endpoints: `organization.apiTokens.access`.
    * `/organizations/{organizationId}/users/{userId}/roles`: `organization.userRoles.access`.

  ## Changed

  * **Schemas:**
    * `Cluster`
      * `secondaryVpcCidr` description updated to "The secondary VPC CIDR. For AWS clusters only."
      * Added `drRegion`, `isDrEnabled`, and `name` to required fields.
    * `OrganizationProductPlan`
      * Added `ENTERPRISE_BUSINESS_CRITICAL` to `productPlanName` enum.

  * **Endpoints:**
    * `/organizations/{organizationId}/users/{userId}/teams`
      * Response schema changed from `TeamsPaginated` to `UserTeamsPaginated`.
      * Permission action changed from `organization.users.get` to `organization.teams.get`.
      * Updated descriptions for parameters and summary.

  * **Removed:**
    * `astroRuntimeVersion` from `UpdateDedicatedDeploymentRequest`, `UpdateHybridDeploymentRequest`, and `UpdateStandardDeploymentRequest`.
</Update>

<Update label="2026-03-16">
  ## Summary

  * Added a new endpoint to list all Teams associated with a specific user.

  ## Added

  * **Endpoints**
    * `GET /organizations/{organizationId}/users/{userId}/teams`: List all Teams that a user belongs to within an Organization. Supports pagination with `offset` and `limit` query parameters, and sorting with the `sorts` query parameter.
</Update>

<Update label="2026-03-10">
  # v1 API Changelog

  ## Summary

  * Added discriminators to `CreateClusterRequest`, `CreateDeploymentRequest`, `UpdateClusterRequest`, and `UpdateDeploymentRequest` schemas. Discriminators remove ambiguity when creating or updating resources by mapping requests to the correct cloud provider or Deployment type.
  * Updated descriptions for `ApiTokenRole` and API token listing parameters.

  ## Added

  * **CreateClusterRequest Schema:**
    * Discriminator on `cloudProvider` with mappings for `AWS`, `AZURE`, and `GCP`.
  * **CreateDeploymentRequest Schema:**
    * Discriminator on `type` with mappings for `DEDICATED`, `HYBRID`, and `STANDARD`.
  * **UpdateClusterRequest Schema:**
    * Discriminator on `clusterType` with mappings for `DEDICATED` and `HYBRID`.
  * **UpdateDeploymentRequest Schema:**
    * Discriminator on `type` with mappings for `DEDICATED`, `HYBRID`, and `STANDARD`.

  ## Changed

  * **UpdateDedicatedDeploymentRequest, UpdateHybridDeploymentRequest, UpdateStandardDeploymentRequest Schemas:**
    * Removed description for `environmentVariables`.
  * **ApiTokenRole Schema:**
    * Updated description for `entityId`.
  * **API Token Listing Endpoint:**
    * Updated description for the parameter related to DAG tags.
</Update>

<Update label="2026-02-23">
  # v1 API Changelog

  ## Summary

  * Added new properties to the `DagRole`, `Deployment`, and `Team` schemas to enhance DAG access management.
  * Introduced new query parameters for pagination and sorting in the `/organizations/{organizationId}/tokens` and `/organizations/{organizationId}/users` endpoints.

  ## Added

  * **Schemas**
    * `DagRole`
      * `dagTag`: DAG tag, required if `DagId` is not specified.
    * `DeploymentEnvironmentVariable`
      * `updatedAt`: Format set to `date-time`.
    * `Invite`
      * `expiresAt`: Format set to `date-time`.
    * `Role`
      * `createdAt` and `updatedAt`: Examples and format set to `date-time`.
    * `RoleWithPermission`
      * `createdAt` and `updatedAt`: Examples and format set to `date-time`.
    * `Team`
      * `dagRoles`: Array of DAG roles.
  * **Endpoints**
    * `/organizations/{organizationId}/tokens`
      * `limit`: Limit for pagination.
      * `sorts`: Sorting criteria.
    * `/organizations/{organizationId}/users`
      * `limit`: Limit for pagination.
      * `sorts`: Sorting criteria.
  * **Enums**
    * `ApiTokenRole`
      * `entityType`: Added `DAG_TAG`.
</Update>

<Update label="2026-01-28">
  Initial release of the v1 Astro API.

  See [Migrate to v1](/docs/astro/api/v-1-beta-1/migrate-v1-api) for key changes and migration steps.
</Update>