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.
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.
The maximum number of API requests you can make with the same API token depends on the type of request you're making:
POSTrequests: You can make a make a maximum of 5 requests per second using the same API token.
DELETErequests: You can make a make a maximum of 5 requests per second using the same API token.
GETrequests: You can make a make a maximum of 10 requests per second using the same API token.
Astro supports different levels of idempotency for different request types.
POSTrequests (Create): Identical
POSTrequests 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.
POSTrequests (Update): Idempotency is guaranteed for all
POSTrequests to update an existing object.
DELETErequests: Idempotency is guaranteed for all
DELETErequests. Any successive identical
DELETErequests 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
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.