Skip to main content

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:

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

info

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

Authentication

All requests to the API must be authenticated. You can use bearer authentication to authenticate with a Workspace API token or Organization API token. The following example shows how you can add a token to a curl request:

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

Endpoints can return subsets of specific attributes based on the permissions of your API token. If your API token's role allows you to access something in the Cloud 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 5 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 10 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 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.
  • 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.

Was this page helpful?

Sign up for Developer Updates

Get a summary of new Astro features once a month.

You can unsubscribe at any time.
By proceeding you agree to our Privacy Policy, our Website Terms and to receive emails from Astronomer.