Astro API

Astro API overview

The Astro API is a standard REST API that you can use to develop applications and scripts for interacting with Astro components.

The API contains multiple schemas. Each schema covers a different part of Astro management:

  • Platform API schema: Includes endpoints for updating your Astro infrastructure and resources, such as clusters, Deployments, and Workspaces.
  • Identity and access management (IAM) API schema: Includes endpoints for managing role-based access control (RBAC) components, such as users and Teams.

To make your first request using the Astro API, see Get started with the Astro API.

The Astro API is currently in beta. See Support for all policies related to using beta releases of the API.

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.

Authentication

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:

1curl --location 'https://api.astronomer.io/platform/v1beta1/organizations/<your-organization-id>/clusters' \
2--header 'Authorization: Bearer <your-api-token>'

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.

Rate limiting

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.

Idempotent requests

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.

API status codes

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

Built with