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

# 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 v1 API provides a unified endpoint for managing your Astro infrastructure and resources, including:

* Organizations, Workspaces, and Deployments
* Clusters and deployment infrastructure
* Users, Teams, and role-based access control (RBAC)
* API tokens and authentication

To make your first request using the Astro API, see [Get started with the Astro API](/docs/astro/api/v-1/get-started).

<Note>
  **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](/docs/astro/api/v-1-beta-1/v1beta1-deprecation-notice) and [migration guide](/docs/astro/api/v-1-beta-1/migrate-v1-api) for details.
</Note>

<Tip>
  Looking to use the Airflow REST API instead? See the [Astro documentation](/docs/astro/airflow-api) to learn how to make requests to Airflow Deployments using the Airflow API.
</Tip>

## Authentication

All requests to the API must be authenticated. You can use [bearer authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/) to authenticate with a [Workspace API token](/docs/astro/workspace-api-tokens), [Organization API token](/docs/astro/organization-api-tokens), or [Deployment API token](/docs/astro/deployment-api-tokens). The following example shows how you can add a token to a curl request:

```curl wrap theme={null}
curl --location 'https://api.astronomer.io/v1/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 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](/docs/astro/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](https://en.wikipedia.org/wiki/Idempotence) 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 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.

## Download OpenAPI specification

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.

* [Astro API v1 specification](https://api.astronomer.io/spec/v1)