The Astro API is a standard REST API that you can use to develop applications and scripts for interacting with Astro components.
The v1 API provides a unified endpoint for managing your Astro infrastructure and resources, including:
To make your first request using the Astro API, see Get started with the Astro API.
Astro API v1 is now generally available. The previous v1beta1 API is deprecated and will reach end of support in January 2027. See the v1beta1 deprecation notice and migration guide for details.
Looking to use the Airflow REST API instead? See the Astro documentation to learn how to make requests to Airflow Deployments using the Airflow API.
All requests to the API must be authenticated. You can use bearer authentication to authenticate with a Workspace API token, Organization API token, or Deployment API token. The following example shows how you can add a token to a curl request:
Endpoints can return subsets of specific attributes based on the permissions of your API token. If your token’s role allows you to access something in the Astro UI or Astro CLI, it also allows you to access the same thing or action using the API. See User permissions for a list of all possible permissions.
The maximum number of API requests you can make with the same API token depends on the type of request you’re making:
POST requests: You can make a make a maximum of 10 requests per second using the same API token.DELETE requests: You can make a make a maximum of 5 requests per second using the same API token.GET requests: You can make a make a maximum of 25 requests per second using the same API token.Astro supports different levels of idempotency for different request types.
POST requests (Create): Identical POST requests to create a new object will result in the creation of multiple objects. For example, if you make identical requests to create an Organization, Astro creates multiple Organizations with identical settings and unique IDs.POST requests (Update): Idempotency is guaranteed for all POST requests to update an existing object.DELETE requests: Idempotency is guaranteed for all DELETE requests. Any successive identical DELETE requests return a 404 error.If the API returns a 200 or 204 code, your API request was a success. If the API returns a 40x or 500 code, your request resulted in one of the following errors:
400: Bad Request - Your request was not successful because it was not formatted properly, possibly due to missing required parameters.401: Unauthorized - Your request did not include an API token.404: Resource Not Found - The resource you’re trying to access does not exist.403: Forbidden - The API token you included did not have sufficient permissions to complete the request.500: Internal server error - The request could not be completed because of an error caused by Astro.All error responses include a requestId that you can share with Astronomer support if you want to learn more about the error.
To export Astro API’s OpenAPI specification for use on another platform, such as Postman or Swagger, download the YAML configuration from the following page and import it into the tool of your choice.