# 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](get-started).
The Astro API is currently in beta. See [Support](versioning-and-support) for all policies related to using beta releases of the API.
Looking to use the Airflow REST API instead? See the [Astro documentation](https://www.astronomer.io/docs/astro/airflow-api) 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](https://swagger.io/docs/specification/authentication/bearer-authentication/) to authenticate with a [Workspace API token](https://www.astronomer.io/docs/astro/workspace-api-tokens), [Organization API token](https://www.astronomer.io/docs/astro/organization-api-tokens), or [Deployment API token](https://www.astronomer.io/docs/astro/deplopyment-api-tokens). The following example shows how you can add a token to a curl request:
```curl
curl --location 'https://api.astronomer.io/platform/v1beta1/organizations//clusters' \
--header 'Authorization: Bearer '
```
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](https://www.astronomer.io/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 specifications
To export Astro API's OpenAPI specifications for use on another platform, such as Postman or Swagger, download the YAML configurations from the following pages and import them into the tool of your choice.
* [Astro API Platform specification](https://api.astronomer.io/spec/platform/v1beta1)
* [Astro API IAM specification](https://api.astronomer.io/spec/iam/v1beta1)
# Get started with the Astro API
> Run a few simple commands to learn how to use the Astro API.
In this quick introduction to the Astro API, you'll make some simple requests to retrieve details about your Organization and create a Workspace API token.
## Prerequisites
* An [Astro account](https://www.astronomer.io/docs/astro/log-in-to-astro).
* An [Organization API token](https://www.astronomer.io/docs/astro/organization-api-tokens) with the Organization Owner role. Astronomer recommends that you create a new API token for this tutorial.
* An Astro [Workspace](https://www.astronomer.io/docs/astro/manage-workspaces).
* A method for making API requests. This tutorial assumes you're using curl, but you can also use tools such as Postman.
## Step 1: Make your first API request
To access most endpoints, you need to provide an Organization ID to the API as a path parameter. One of the few requests that doesn't require an Organization ID is the [List Organizations](https://www.astronomer.io/docs/astro/api/platform-api-reference#tag/Organization/operation/ListOrganizations) request, which means that you can programmatically retrieve an Organization ID.
To retrieve the Organization ID through the API, run the following command:
```bash
curl --location 'https://api.astronomer.io/platform/v1beta1/organizations' \
--header 'Authorization: Bearer '
```
If the command was successful, then you receive a response that begins similarly to the following:
```json {14}
{
"organizations": [
{
"billingEmail": "billing@example.com",
"createdAt": "2022-11-22T04:37:12T",
"createdBySubject": {
"apiTokenName": "my-token",
"avatarUrl": "https://avatar.url",
"fullName": "Jane Doe",
"id": "clm8qv74h000008mlf08scq7k",
"subjectType": "USER",
"username": "user1@example.com"
},
"id": "clmaxoarx000008l2c5ayb9pt",
"isScimEnabled": false,
...
],
```
Copy the top-level `id` from this response. This is your Organization ID.
While you could have retrieved this value manually from the Astro UI, using the API lets you script this workflow and execute it on a regular basis.
## Step 2: Request Workspace details from the API
Using the Organization ID you copied, you can now find the ID for the Workspace where you want to create your API token.
Run the following command to list all Workspaces in your Organization:
```bash
curl --location 'https://api.astronomer.io/platform/v1beta1/organizations//workspaces' \
--header 'Authorization: Bearer '
```
If the command succeeds, the API returns a list of Workspaces similar to the following:
```json {15}
{
"workspaces": [
{
"cicdEnforcedDefault": true,
"createdAt": "2023-09-08T12:00:00Z",
"createdBy": {
"apiTokenName": "my-token",
"avatarUrl": "https://avatar.url",
"fullName": "Jane Doe",
"id": "clm8qv74h000008mlf08scq7k",
"subjectType": "USER",
"username": "user1@example.com"
},
"description": "This is a test workspace",
"id": "clm8t5u4q000008jq4qoc3036",
"name": "My Workspace",
"organizationId": "clm8t5u4q000008jq4qoc3036",
"organizationName": "My Organization",
"updatedAt": "2023-09-08T13:30:00Z",
"updatedBy": {
"apiTokenName": "my-token",
"avatarUrl": "https://avatar.url",
"fullName": "Jane Doe",
"id": "clm8qv74h000008mlf08scq7k",
"subjectType": "USER",
"username": "user1@example.com"
}
}
]
}
```
In the response for your specific Workspace, copy the top-level `id`. This is your Workspace ID.
If the API returns too many Workspaces, add some pagination parameters to your URL. For example, to limit your results to only the 20 most recently updated Workspaces, you can run:
```bash
curl --location 'https://api.astronomer.io/platform/v1beta1/organizations//workspaces?limit=20&sorts=updatedAt:asc' \
--header 'Authorization: Bearer '
```
## Step 3: Update your token description using the API
Now that you have both an Organization ID and a Workspace ID, you can create a Workspace API token using the Astro API.
1. Run the following command to create a new Workspace API token:
```bash
curl --location 'https://api.astronomer.io/iam/v1beta1/organizations//tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data '{
"description": "I wrote this description using the Astro API!",
"entityId": "",
"name": "My new API token",
"role": "WORKSPACE_MEMBER",
"type": "WORKSPACE"
}'
```
If the request was successful, the API will return a response with your new token's details.
2. In the Astro UI, go to **Workspace Settings** > **Access Management** > **API Tokens** and find your Workspace API token. You should see your updated description under **Description**.
# Astro API versioning, maintenance, and support
> Learn how Astronomer versions and maintains the Astro API.
The Astro API is currently in beta. The following policies apply to all beta versions of the Astro API.
## Releases and versioning
All API endpoints include a release name in their URL that determines which release of the API you use.
Each Astro API release name includes both a major version number and a release number, formatted as `beta`. For example, `v2beta3` is the third release of the second major version.
For a given release, Astronomer can make non-breaking changes in place without incrementing the release name. Astronomer can make breaking changes, also known as backward-incompatible changes, only between new releases. See [Version upgrades and breaking changes](#version-upgrades-and-breaking-changes).
## Deprecations
Astronomer reserves the right to mark specific API endpoints or features as deprecated within a given release. When an API endpoint is marked as deprecated, you will receive a notification and have 90 days to migrate away from the endpoint. After 90 days, Astronomer can make breaking changes to the endpoint, even within the same release.
## Version upgrades and breaking changes
Any upgrade between versioned API releases can include breaking changes, including for non-deprecated endpoints. For example, an upgrade from `v1beta1` to `v1beta2` can include breaking changes. However, another release of `v1beta1` can include a breaking change to an endpoint only if the endpoint has been marked as deprecated for at least 90 days.
## API support
Astronomer offers support only for the two most recent releases at any given time. If you are on an earlier version that's out of support, you must upgrade to one of the two most recent versions to receive support. Support cases for beta releases of the Astro API are treated with lower priority than other generally available Astro features.
Astronomer reserves the right to shut down endpoints for a given beta release one year after all of its endpoints have equivalent functionality in a stable version.
# List Organizations
```http
GET https://api.astronomer.io/platform/v1beta1/organizations
```
List the details about all Organizations that you have access to. Requires using a personal access token (PAT) for authentication.
## Query Parameters
- SupportPlan (optional): Filters the Organization list by support plan.
- Product (optional): Filters the Organization list by product.
- Offset (optional): The number of results to skip before returning values.
- Limit (optional): The maximum number of results to return.
- Sorts (optional): A list of field names to sort by, and whether to show results as ascending or descending. Formatted as `:asc` or `:desc`.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations \
-H "Authorization: Bearer "
```
# Get an Organization
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}
```
Retrieve information about a specific Organization.
## Path Parameters
- OrganizationId (required): The Organization's ID.
## Query Parameters
- IsLookUpOnly (optional): Whether to show only Organization metadata.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId \
-H "Authorization: Bearer "
```
# Update an Organization
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}
Content-Type: application/json
```
Update an Organization's details.
## Path Parameters
- OrganizationId (required): The Organization's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"billingEmail": "billing@company.com",
"isScimEnabled": false,
"name": "My Organization"
}'
```
# Get Organization audit logs
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/audit-logs
```
Retrieve logs across a specified time period for an Organization.
## Path Parameters
- OrganizationId (required): The ID of the Organization to retrieve audit logs for.
## Query Parameters
- StartDate (optional): The start date of the logs.
- EndDate (optional): The end date of the logs.
## Response Body
- 200: OK
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/audit-logs \
-H "Authorization: Bearer "
```
# List alerts
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/alerts
```
List alerts.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the alerts belong to.
## Query Parameters
- AlertIds (optional): A list of IDs for specific alerts to list. The API returns details for all alerts which have been specified in this list.
- DeploymentIds (optional): A list of deployment IDs the alerts belong to. The API returns details for all alerts belonging only to the specified Deployments.
- WorkspaceIds (optional): A list of workspace IDs the alerts belong to. The API returns details for all alerts belonging only to the specified Workspaces.
- AlertTypes (optional): A list of types for specific alerts to filter by. The API returns details for all alerts belonging only to the specified alert types.
- EntityType (optional): The type of the entity the alerts belong to.
- Offset (optional): The number of results to skip before returning values.
- Limit (optional): The maximum number of results to return.
- Sorts (optional): A list of field names to sort by, and whether to show results as ascending or descending. Formatted as `:asc` or `:desc`.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/alerts \
-H "Authorization: Bearer "
```
# Create an alert
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/alerts
Content-Type: application/json
```
Create an alert.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the alert will belong to.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/alerts \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"entityId": "entityId",
"entityType": "DEPLOYMENT",
"name": "name",
"notificationChannelIds": [
"notificationChannelIds"
],
"rules": {
"patternMatches": [
{
"entityType": "DAG_ID TASK_ID",
"operatorType": "IS IS_NOT INCLUDES EXCLUDES",
"values": [
"values"
]
}
],
"properties": {
"dagDurationSeconds": 0,
"deploymentId": "deploymentId"
}
},
"severity": "INFO",
"type": "DAG_SUCCESS"
}'
```
# Get an alert
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/alerts/{alertId}
```
Get an alert.
## Path Parameters
- OrganizationId (required): The ID of the Organization the alert belongs to.
- AlertId (required): The ID of the alert to get.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/alerts/alertId \
-H "Authorization: Bearer "
```
# Update an alert
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/alerts/{alertId}
Content-Type: application/json
```
Update an alert.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the alert belongs to.
- AlertId (required): The ID of the alert to update.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/alerts/alertId \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "name",
"notificationChannelIds": [
"notificationChannelIds"
],
"rules": {
"patternMatches": [
{
"entityType": "DAG_ID TASK_ID",
"operatorType": "IS IS_NOT INCLUDES EXCLUDES",
"values": [
"values"
]
}
],
"properties": {
"dagDurationSeconds": 0
}
},
"severity": "INFO",
"type": "DAG_SUCCESS"
}'
```
# Delete an alert
```http
DELETE https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/alerts/{alertId}
```
Delete an alert.
## Path Parameters
- OrganizationId (required): The ID of the Organization the alert belongs to.
- AlertId (required): The ID of the alert to delete.
## Response Body
- 204:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X DELETE https://api.astronomer.io/platform/v1beta1/organizations/organizationId/alerts/alertId \
-H "Authorization: Bearer "
```
# Get cluster options
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/cluster-options
```
Get all possible options for configuring a cluster.
## Path Parameters
- OrganizationId (required): The ID of the Organization to get cluster options for.
## Query Parameters
- Provider (optional): The cluster's cloud provider.
- Type (required): The cluster type.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -G https://api.astronomer.io/platform/v1beta1/organizations/organizationId/cluster-options \
-H "Authorization: Bearer " \
-d type=DEDICATED
```
# Get Deployment options
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployment-options
```
Get the options available for configuring a Deployment.
## Path Parameters
- OrganizationId (required): The ID of the Organization to retrieve Deployment options for.
## Query Parameters
- DeploymentId (optional): The ID of a Deployment to retrieve options for.
- DeploymentType (optional): The runtime type of the deployment.
- Executor (optional): The executor of the deployment.
- CloudProvider (optional): The cloud provider of the cluster for the deployment.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployment-options \
-H "Authorization: Bearer "
```
# List clusters
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/clusters
```
List clusters in an Organization.
## Path Parameters
- OrganizationId (required): The Organization's unique ID.
## Query Parameters
- Names (optional): A list of names for Clusters to filter by. The API returns details only for the specified Clusters.
- Provider (optional): The cloud provider to list clusters for. Clusters from other providers will be filtered out of the results.
- Offset (optional): The number of results to skip before returning values.
- Limit (optional): The maximum number of results to return.
- Sorts (optional): A list of field names to sort by, and whether to show results as ascending or descending. Formatted as `:asc` or `:desc`.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/clusters \
-H "Authorization: Bearer "
```
# Create a cluster
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/clusters
Content-Type: application/json
```
Create a cluster in the Organization. An Astro cluster is a Kubernetes cluster that hosts the infrastructure required to run Deployments.
## Path Parameters
- OrganizationId (required): The ID of the Organization to create the cluster in.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 412: Precondition Failed
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/clusters \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"cloudProvider": "AZURE",
"dbInstanceType": "Small General Purpose",
"k8sTags": [
{
"key": "key1",
"value": "value1"
}
],
"name": "My cluster",
"nodePools": [
{
"isDefault": true,
"maxNodeCount": 10,
"name": "my-nodepool",
"nodeInstanceType": "t3.medium"
}
],
"providerAccount": "provider-account",
"region": "us-east-1",
"type": "DEDICATED",
"vpcSubnetRange": "172.20.0.0/22",
"workspaceIds": [
"workspaceIds"
]
}'
```
# Get a cluster
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/clusters/{clusterId}
```
Retrieve details about a cluster.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the cluster belongs.
- ClusterId (required): The cluster's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/clusters/clusterId \
-H "Authorization: Bearer "
```
# Update a cluster
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/clusters/{clusterId}
Content-Type: application/json
```
Update a cluster in the Organization.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the cluster belongs.
- ClusterId (required): The cluster's ID
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 412: Precondition Failed
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/clusters/clusterId \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"clusterType": "DEDICATED",
"dbInstanceType": "Small General Purpose",
"k8sTags": [
{
"key": "key1",
"value": "value1"
}
],
"name": "My cluster",
"nodePools": [
{
"id": "clm8bvk8b000008l9deowc5lx",
"isDefault": true,
"maxNodeCount": 10,
"name": "my-nodepool",
"nodeInstanceType": "t3.medium"
}
],
"workspaceIds": [
"workspaceIds"
]
}'
```
# Delete a cluster
```http
DELETE https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/clusters/{clusterId}
```
Delete a cluster.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the cluster belongs.
- ClusterId (required): The cluster's ID.
## Response Body
- 204:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X DELETE https://api.astronomer.io/platform/v1beta1/organizations/organizationId/clusters/clusterId \
-H "Authorization: Bearer "
```
# List Deployments
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments
```
List Deployments in an Organization.
## Path Parameters
- OrganizationId (required): The ID of the Organization to list Deployments for.
## Query Parameters
- DeploymentIds (optional): A list of IDs for Deployments to show. The API returns details only for the specified Deployments.
To list multiple Deployments, you must string together the parameter with the `deploymentIds`. For example, `deployments?deploymentIds=deploymentId1&deploymentIds=deploymentId2`
- Names (optional): A list of names for Deployments to filter by. The API returns details only for the specified Deployments.
- WorkspaceIds (optional): A list of IDs for Workspaces to filter on. The API returns details for all Deployments belonging only to the specified Workspaces.
- Offset (optional): The number of results to skip before returning values.
- Limit (optional): The maximum number of results to return.
- Sorts (optional): A list of field names to sort by, and whether to show results as ascending or descending. Formatted as `:asc` or `:desc`.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments \
-H "Authorization: Bearer "
```
# Create a Deployment
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments
Content-Type: application/json
```
Create a Deployment in the Organization. An Astro Deployment is an Airflow environment that is powered by all core Airflow components.
## Path Parameters
- OrganizationId (required): The ID of the Organization in which to create the Deployment.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"astroRuntimeVersion": "9.1.0",
"clusterId": "clmh9g6zj000008mg77if5wa2",
"contactEmails": [
"user1@company.com"
],
"defaultTaskPodCpu": "0.5",
"defaultTaskPodMemory": "1Gi",
"description": "My deployment description",
"environmentVariables": [
{
"isSecret": false,
"key": "my-var",
"value": "my-var-value"
}
],
"executor": "CELERY",
"isCicdEnforced": true,
"isDagDeployEnabled": true,
"isDevelopmentMode": false,
"isHighAvailability": true,
"name": "My deployment",
"resourceQuotaCpu": "160",
"resourceQuotaMemory": "320Gi",
"scalingSpec": {
"hibernationSpec": {
"override": {
"isHibernating": false,
"overrideUntil": "overrideUntil"
},
"schedules": [
{
"description": "description",
"hibernateAtCron": "hibernateAtCron",
"isEnabled": false,
"wakeAtCron": "wakeAtCron"
}
]
}
},
"schedulerSize": "MEDIUM",
"type": "DEDICATED",
"workerQueues": [
{
"astroMachine": "A5",
"id": "clmha1mzc000b08mi96n182au",
"isDefault": true,
"maxWorkerCount": 0,
"minWorkerCount": 0,
"name": "My worker queue",
"workerConcurrency": 0
}
],
"workloadIdentity": "arn:aws:iam::123456789:role/AirflowS3Logs-clmk2qqia000008mhff3ndjr0",
"workspaceId": "clmh8ol3x000008jo656y4285"
}'
```
# Get a Deployment
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments/{deploymentId}
```
Retrieve details about a Deployment.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Deployment belongs.
- DeploymentId (required): The Deployment's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId \
-H "Authorization: Bearer "
```
# Update a Deployment
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments/{deploymentId}
Content-Type: application/json
```
Update a Deployment in the Organization.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Deployment belongs.
- DeploymentId (required): The Deployment's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"contactEmails": [
"user1@company.com"
],
"defaultTaskPodCpu": "0.5",
"defaultTaskPodMemory": "1Gi",
"description": "My deployment description",
"environmentVariables": [
{
"isSecret": false,
"key": "my-var",
"value": "my-var-value"
}
],
"executor": "CELERY",
"isCicdEnforced": true,
"isDagDeployEnabled": true,
"isDevelopmentMode": false,
"isHighAvailability": true,
"name": "My deployment",
"resourceQuotaCpu": "160",
"resourceQuotaMemory": "320Gi",
"scalingSpec": {
"hibernationSpec": {
"override": {
"isHibernating": false,
"overrideUntil": "overrideUntil"
},
"schedules": [
{
"description": "description",
"hibernateAtCron": "hibernateAtCron",
"isEnabled": false,
"wakeAtCron": "wakeAtCron"
}
]
}
},
"schedulerSize": "MEDIUM",
"type": "DEDICATED",
"workerQueues": [
{
"astroMachine": "A5",
"id": "clmha1mzc000b08mi96n182au",
"isDefault": true,
"maxWorkerCount": 0,
"minWorkerCount": 0,
"name": "My worker queue",
"workerConcurrency": 0
}
],
"workloadIdentity": "arn:aws:iam::123456789:role/AirflowS3Logs-clmk2qqia000008mhff3ndjr0",
"workspaceId": "clmh7vdf4000008lhhlnk9t6o"
}'
```
# Delete a Deployment
```http
DELETE https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments/{deploymentId}
```
Delete a Deployment from an Organization.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Deployment belongs.
- DeploymentId (required): The Deployment's ID.
## Response Body
- 204:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X DELETE https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId \
-H "Authorization: Bearer "
```
# Configure a hibernation override for a deployment
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments/{deploymentId}/hibernation-override
Content-Type: application/json
```
## Path Parameters
- OrganizationId (required): The Organization ID
- DeploymentId (required): The Deployment ID
## Response Body
- 200: OK
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId/hibernation-override \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"isHibernating": false,
"overrideUntil": "overrideUntil"
}'
```
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId/hibernation-override \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"isHibernating": false,
"overrideUntil": "overrideUntil"
}'
```
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId/hibernation-override \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"isHibernating": false,
"overrideUntil": "overrideUntil"
}'
```
# Delete a hibernation override for a deployment
```http
DELETE https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments/{deploymentId}/hibernation-override
```
## Path Parameters
- OrganizationId (required): The Organization ID
- DeploymentId (required): The Deployment ID
## Response Body
- 204: No Content
## Examples
```shell
curl -X DELETE https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId/hibernation-override \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId/hibernation-override \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId/hibernation-override \
-H "Authorization: Bearer "
```
# List deploys for a deployment
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments/{deploymentId}/deploys
```
List deploys for a deployment
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Deployment belongs.
- DeploymentId (required): The Deployment's ID.
## Query Parameters
- Offset (optional): The number of results to skip before returning values.
- Limit (optional): The maximum number of results to return.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId/deploys \
-H "Authorization: Bearer "
```
# Create a Deploy
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments/{deploymentId}/deploys
Content-Type: application/json
```
Create a new Deploy. A Deploy represents an intent to deploy new DAG code to an Astro Deployment.
## Path Parameters
- OrganizationId (required): The ID of the Organization in which to create the Deployment.
- DeploymentId (required): The Deployment's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId/deploys \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"bundleMountPath": "bundleMountPath",
"bundleType": "dbt",
"description": "My deploy description",
"type": "IMAGE_AND_DAG"
}'
```
# Get a deploy for a deployment
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments/{deploymentId}/deploys/{deployId}
```
Get a deploy for a deployment
## Path Parameters
- OrganizationId (required): The ID of the Organization in which to create the Deployment.
- DeploymentId (required): The Deployment's ID.
- DeployId (required): The Deploy's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId/deploys/deployId \
-H "Authorization: Bearer "
```
# Update a Deploy
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments/{deploymentId}/deploys/{deployId}
Content-Type: application/json
```
Update an existing Deploy. A Deploy represents an intent to deploy new DAG code to an Astro Deployment.
## Path Parameters
- OrganizationId (required): The ID of the Organization in which to create the Deployment.
- DeploymentId (required): The Deployment's ID.
- DeployId (required): The Deploy's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId/deploys/deployId \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"description": "My deploy description"
}'
```
# Finalize a deploy
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments/{deploymentId}/deploys/{deployId}/finalize
Content-Type: application/json
```
Finalize a deploy that you initialized using the `deploys` endpoint.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Deployment belongs.
- DeploymentId (required): The Deployment's ID.
- DeployId (required): The deploy's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId/deploys/deployId/finalize \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"bundleTarballVersion": "bundleTarballVersion",
"dagTarballVersion": "dagTarballVersion"
}'
```
# Deploy rollback of a deployment
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/deployments/{deploymentId}/deploys/{deployId}/rollback
Content-Type: application/json
```
Deploy rollback of a deployment
## Path Parameters
- OrganizationId (required): The ID of the Organization in which to create the Deployment.
- DeploymentId (required): The Deployment's ID.
- DeployId (required): The Deploy's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/deployments/deploymentId/deploys/deployId/rollback \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"description": "description"
}'
```
# List environment objects
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/environment-objects
```
List environment objects in a Workspace or Deployment.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the environment object belongs.
## Query Parameters
- Offset (optional): The number of results to skip before returning values.
- Limit (optional): The maximum number of results to return.
- Sorts (optional): A list of field names to sort by, and whether to show results as ascending or descending. Formatted as `:asc` or `:desc`.
- WorkspaceId (optional): The Workspace ID to filter for. The API returns details for all environment objects belonging only to this specified Workspace.
- DeploymentId (optional): The Deployment ID to filter for. The API returns details for all environment objects belonging only to this specified Deployment.
- ObjectType (optional): The environment object type to filter for. The API returns details for all environment objects belonging only to this specified object type.
- ObjectKey (optional): The environment object key to filter for. The API returns details for all environment objects belonging only to the specified object key.
- ShowSecrets (optional): If true, returns the actual values of fields of type secret in the API response.
- ResolveLinked (optional): Resolve and return the environment objects linked to the specified Deployment or Workspace in the API response.
## Response Body
- 200: OK
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 405: Method Not Allowed
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/environment-objects \
-H "Authorization: Bearer "
```
# Create a new environment object
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/environment-objects
Content-Type: application/json
```
Create an environment object for a Deployment or Workspace. An environment object represents a connection, Airflow variable, or metrics export resource that is managed by the Astro Environment Manager.
## Path Parameters
- OrganizationId (required): The ID of the Organization in which to create the environment object.
## Response Body
- 200: OK
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 405: Method Not Allowed
- 409: Conflict
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/environment-objects \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"airflowVariable": {
"isSecret": false,
"value": "value"
},
"autoLinkDeployments": false,
"connection": {
"authTypeId": "authTypeId",
"extra": {},
"host": "host",
"login": "login",
"password": "password",
"port": 0,
"schema": "schema",
"type": "type"
},
"excludeLinks": [
{
"scope": "DEPLOYMENT",
"scopeEntityId": "scopeEntityId"
}
],
"links": [
{
"overrides": {
"airflowVariable": {
"value": "value"
},
"connection": {
"extra": {},
"host": "host",
"login": "login",
"password": "password",
"port": 0,
"schema": "schema",
"type": "type"
},
"metricsExport": {
"basicToken": "basicToken",
"endpoint": "endpoint",
"exporterType": "PROMETHEUS",
"headers": {},
"labels": {},
"password": "password",
"username": "username"
}
},
"scope": "DEPLOYMENT",
"scopeEntityId": "scopeEntityId"
}
],
"metricsExport": {
"basicToken": "basicToken",
"endpoint": "endpoint",
"exporterType": "PROMETHEUS",
"headers": {},
"labels": {},
"password": "password",
"username": "username"
},
"objectKey": "objectKey",
"objectType": "CONNECTION",
"scope": "WORKSPACE",
"scopeEntityId": "scopeEntityId"
}'
```
# Get environment object
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/environment-objects/{environmentObjectId}
```
Retrieve details about an environment object.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the environment object belongs.
- EnvironmentObjectId (required): The environment object's ID.
## Response Body
- 200: OK
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 405: Method Not Allowed
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/environment-objects/environmentObjectId \
-H "Authorization: Bearer "
```
# Update an environment object
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/environment-objects/{environmentObjectId}
Content-Type: application/json
```
Update an existing Deployment level or Workspace level environment object.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the environment object belongs.
- EnvironmentObjectId (required): The environment object's ID.
## Response Body
- 200: OK
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 405: Method Not Allowed
- 409: Conflict
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/environment-objects/environmentObjectId \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"airflowVariable": {
"value": "value"
},
"autoLinkDeployments": false,
"connection": {
"authTypeId": "authTypeId",
"extra": {},
"host": "host",
"login": "login",
"password": "password",
"port": 0,
"schema": "schema",
"type": "type"
},
"excludeLinks": [
{
"scope": "DEPLOYMENT",
"scopeEntityId": "scopeEntityId"
}
],
"links": [
{
"overrides": {
"airflowVariable": {
"value": "value"
},
"connection": {
"extra": {},
"host": "host",
"login": "login",
"password": "password",
"port": 0,
"schema": "schema",
"type": "type"
},
"metricsExport": {
"basicToken": "basicToken",
"endpoint": "endpoint",
"exporterType": "PROMETHEUS",
"headers": {},
"labels": {},
"password": "password",
"username": "username"
}
},
"scope": "DEPLOYMENT",
"scopeEntityId": "scopeEntityId"
}
],
"metricsExport": {
"basicToken": "basicToken",
"endpoint": "endpoint",
"exporterType": "PROMETHEUS",
"headers": {},
"labels": {},
"password": "password",
"username": "username"
}
}'
```
# Delete an environment object
```http
DELETE https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/environment-objects/{environmentObjectId}
```
Delete an environment object from a Deployment or Workspace.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the environment object belongs.
- EnvironmentObjectId (required): The environment object's ID.
## Response Body
- 204:
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 405: Method Not Allowed
- 409: Conflict
- 500: Internal Server Error
## Examples
```shell
curl -X DELETE https://api.astronomer.io/platform/v1beta1/organizations/organizationId/environment-objects/environmentObjectId \
-H "Authorization: Bearer "
```
# Exclude linking an environment object
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/environment-objects/{environmentObjectId}/exclude-linking
Content-Type: application/json
```
Exclude a specific Deployment from linking to an environment object created at the Workspace level.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the environment object belongs.
- EnvironmentObjectId (required): The environment object's ID.
## Response Body
- 200:
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 405: Method Not Allowed
- 409: Conflict
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/environment-objects/environmentObjectId/exclude-linking \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"scope": "DEPLOYMENT",
"scopeEntityId": "scopeEntityId"
}'
```
# List Alert Notification Channels
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/notification-channels
```
List Alert Notification Channels.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Notification Channels belong.
## Query Parameters
- NotificationChannelIds (optional): A list of IDs of specific Notification Channels to list. The API will list information only for Notification Channels which have been specified in this list.
- DeploymentIds (optional): A list of Deployment IDs to filter by, not allowed if Workspace IDs are provided. Returns Notification Channels scoped to these Deployments, plus any shared Organization or Workspace Notification Channels accessible to them.
- WorkspaceIds (optional): A list of Workspace IDs to filter by, not allowed if Deployment IDs are provided. Returns Notification Channels scoped to these Workspaces, plus any shared Organization or Deployment Notification Channels accessible to them.
- ChannelTypes (optional): A list of Notification Channel types to filter by.
- EntityType (optional): The type of entity the Notification Channels belong to.
- Offset (optional): The number of results to skip before returning values.
- Limit (optional): The maximum number of results to return.
- Sorts (optional): A list of field names to sort by, and whether to show results as ascending or descending. Formatted as `:asc` or `:desc`.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/notification-channels \
-H "Authorization: Bearer "
```
# Create an Alert Notification Channel
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/notification-channels
Content-Type: application/json
```
Create an Alert Notification Channel.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Notification Channel will belong.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/notification-channels \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"definition": {
"dagId": "dagId",
"deploymentApiToken": "deploymentApiToken",
"deploymentId": "deploymentId"
},
"entityId": "entityId",
"entityType": "ORGANIZATION",
"isShared": false,
"name": "name",
"type": "SLACK"
}'
```
# Get an Alert Notification Channel
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/notification-channels/{notificationChannelId}
```
Get an Alert Notification Channel.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Notification Channel belongs.
- NotificationChannelId (required): The ID of the Notification Channel to get.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/notification-channels/notificationChannelId \
-H "Authorization: Bearer "
```
# Update an Alert Notification Channel
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/notification-channels/{notificationChannelId}
Content-Type: application/json
```
Update an Alert Notification Channel.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Notification Channel belongs.
- NotificationChannelId (required): The ID of the Notification Channel to update.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/notification-channels/notificationChannelId \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"definition": {
"dagId": "dagId",
"deploymentApiToken": "deploymentApiToken",
"deploymentId": "deploymentId"
},
"isShared": false,
"name": "name",
"type": "SLACK"
}'
```
# Delete an Alert Notification Channel
```http
DELETE https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/notification-channels/{notificationChannelId}
```
Delete an Alert Notification Channel.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Notification Channel belongs.
- NotificationChannelId (required): The ID of the Notification Channel to delete.
## Response Body
- 204:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X DELETE https://api.astronomer.io/platform/v1beta1/organizations/organizationId/notification-channels/notificationChannelId \
-H "Authorization: Bearer "
```
# List Workspaces
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/workspaces
```
List Workspaces in an Organization
## Path Parameters
- OrganizationId (required): The ID of the Organization to list Workspaces for.
## Query Parameters
- WorkspaceIds (optional): A list of IDs for specific Workspaces to list. The API will list information only for Workspaces which have been specified in this list.
To list multiple Workspaces, you must string together the parameter with the `workspaceIds`. For example, `workspaces?workspaceIds=workspaceId1&workspaceIds=workspaceId2`
- Names (optional): A list of names for specific Workspaces to filter by. The API will list information only for Workspaces which have been specified in this list.
- Offset (optional): The number of results to skip before returning values.
- Limit (optional): The maximum number of results to return.
- Sorts (optional): A list of field names to sort by, and whether to show results as ascending or descending. Formatted as `:asc` or `:desc`.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/workspaces \
-H "Authorization: Bearer "
```
# Create Workspace
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/workspaces
Content-Type: application/json
```
Create a Workspace.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Workspace will belong.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/workspaces \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"cicdEnforcedDefault": true,
"description": "This is a test workspace",
"name": "My Workspace"
}'
```
# Get Workspace
```http
GET https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/workspaces/{workspaceId}
```
Get information about a Workspace.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Workspace belongs.
- WorkspaceId (required): The Workspace's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/platform/v1beta1/organizations/organizationId/workspaces/workspaceId \
-H "Authorization: Bearer "
```
# Update Workspace
```http
POST https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/workspaces/{workspaceId}
Content-Type: application/json
```
Update a Workspace.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Workspace belongs.
- WorkspaceId (required): The Workspace's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/platform/v1beta1/organizations/organizationId/workspaces/workspaceId \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"cicdEnforcedDefault": true,
"description": "This is a test workspace",
"name": "My Workspace"
}'
```
# Delete Workspace
```http
DELETE https://api.astronomer.io/platform/v1beta1/organizations/{organizationId}/workspaces/{workspaceId}
```
Delete a Workspace.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Workspace belongs.
- WorkspaceId (required): The Workspace's ID.
## Response Body
- 204:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X DELETE https://api.astronomer.io/platform/v1beta1/organizations/organizationId/workspaces/workspaceId \
-H "Authorization: Bearer "
```
# February 26, 2025
## Summary
Added the ability to work with [Astro Alerts](https://www.astronomer.io/docs/astro/alerts/) and their [Notification Channels](https://www.astronomer.io/docs/astro/alerts/#notification-channels) through the Astro API, with the new `alerts` and `notification-channels` endpoints.
### Added
New endpoints:
- `GET /organizations/{organizationId}/alerts` to list Alerts in a Workspace or Deployment.
- `POST /organizations/{organizationId}/alerts` to create an Alert for a Deployment or Workspace.
- `GET /organizations/{organizationId}/alerts/{alertId}` to retrieve details about a specific Alert.
- `POST /organizations/{organizationId}/alerts/{alertId}` to update an existing Alert.
- `DEL /organizations/{organizationId}/alerts/{alertId}` to delete an Alert.
- `GET /organizations/{organizationId}/notification-channels` to list Alert Notification Channels.
- `POST /organizations/{organizationId}/notification-channels` to create an Alert Notification Channel.
- `GET /organizations/{organizationId}/alerts/{notificationChannelId}` to retrieve details about a specific Alert Notification Channel.
- `POST /organizations/{organizationId}/alerts/{notificationChannelId}` to update an existing Alert Notification Channel.
- `DEL /organizations/{organizationId}/alerts/{notificationChannelId}` to delete an Alert Notification Channel.
# December 10, 2024
## Summary
Added the new schmea, `bundle`, as a deploy type for the Deploy endpoint, allowing you to use [dbt deploys](https://www.astronomer.io/docs/astro/deploy-dbt-project/#option-2) via the Astro API.
## Added
New object schema for the `Deploy` object at `/organizations/{organizationId}/deployments/{deploymentId}/deploys`:
- `Bundle`
Which includes the following new properties:
- `bundleType`
- `currentVersion`
- `deployId`
- `desiredVersion`
- `mountPath`
New properties are also added to the following endpoints:
- `POST organizations/{organizationId}/deployments/{deploymentId}/deploys`
- `bundleMountPath`
- `bundleType`
- `GET organizations/{organizationId}/deployments/{deploymentId}/deploys/{deployId}`
- `bundleMountPath`
- `bundleUploadUrl`
- `bundles`
- `POST organizations/{organizationId}/deployments/{deploymentId}/deploys/{deployId}/finalize`:
- `bundleTarballVersion`
# November 19, 2024
## Summary
Added the ability to retrieve audit logs using the Astro API call, `GET /organizations/{organizationId}/audit-logs`. You can also use the parameters `startDate` and `endDate` to limit the number of logs you retrieve to a particular timescale.
See [Audit logs reference](https://www.astronomer.io/docs/astro/audit-logs/#audit-logs-reference) for more information.
### Added
- `GET /organizations/{organizationId}/audit-logs` - to retrieve audit logs via the API. Note that this API call has a non-configurable rate limit of `2` per minute.
# November 13, 2024
## Summary
Added the ability to work with the Astro Environment Manager through the Astro API, with the new `environment-objects` endpoint. Environment Objects are the API representation of the different functionalities the Environment Manager supports such as Universal Metrics Export, Airflow Variables, and Connections.
To learn more about the different Astro Environment Manger functionality, which you can now access using the Astro API, see:
- [Manage connections and variables](https://www.astronomer.io/docs/astro/manage-connections-variables)
- [Create Airflow connections in the Astro UI](https://www.astronomer.io/docs/astro/create-and-link-connections)
- [Create Airflow variables in the Astro UI](https://www.astronomer.io/docs/astro/create-and-link-variables)
- [Export metrics from Astro](https://www.astronomer.io/docs/astro/export-metrics)
### Added
- `GET /organizations/{organizationId}/environment-objects` to list environment objects in a Workspace or Deployment.
- `POST /organizations/{organizationId}/environment-objects` to create an environment object for a Deployment or Workspace.
- `GET /organizations/{organizationId}/environment-objects/{environmentObjectId}` to retrieve details about a specific environment object.
- `POST /organizations/{organizationId}/environment-objects/{environmentObjectId}` to update an existing Deployment-level or Workspace-level environment object.
- `DEL /organizations/{organizationId}/environment-objects/{environmentObjectId}` to delete an environment object from a Deployment or Workspace.
- `POST /organizations/{organizationId}/environment-objects/{environmentObjectId}/exclude-linking` to exclude a specific Deployment from linking to an environment object created at the Workspace level.
# September 9, 2024
## Summary
This update introduces new possible values for using the Extra Large scheduler size for the `https://api.astronomer.io/platform/v1beta1/organizations/:organizationId/deployments` endpoint. This scheduler size includes the new separate DAG Processor, which improves scheduler performance and reliability. See [Scheduler](https://www.astronomer.io/docs/astro/deployment-resources#scheduler) for more information.
### Added
The new `EXTRA_LARGE` value for `schedulerSize` attributes for creating, updating, and listing Deployments.
# July 31, 2024
## Summary
This update introduces new endpoints for managing IP access lists. See [Astro IP access list documentation](https://www.astronomer.io/docs/astro/ip-access-list) for more information.
# July 10, 2024
## Summary
This update introduces new endpoints for retrieving the health statuses your clusters. See [Astro dedicated cluster documentation](https://www.astronomer.io/docs/astro/create-dedicated-cluster) for more information.
### Added
New object schemas:
- `ClusterHealthStatus`
- `ClusterHealthStatusDetail`
# June 18, 2024
- The endpoint `GET organizations/:organizationId/clusters/:clusterId` now includes the status, `UPGRADE_PENDING`.
# June 11, 2024
- The endpoint `GET organizations/:organizationId/clusters/:clusterId` now includes the status, `ACCESS_DENIED`.
# May 15, 2024
## Summary
This update introduces new endpoints for managing deploys, including image deploys, DAG deploys, and deploy rollbacks. See [Astro documentation](https://docs.astronomer.io/astro/deploy-code) for more information.
### Added
New endpoints:
- `GET /organizations/{organizationId}/deployments/{deploymentId}/deploys` to list deploys for a deployment.
- `POST /organizations/{organizationId}/deployments/{deploymentId}/deploys` to create a new deploy.
- `GET /organizations/{organizationId}/deployments/{deploymentId}/deploys/{deployId}` to retrieve a specific deploy.
- `POST /organizations/{organizationId}/deployments/{deploymentId}/deploys/{deployId}` to update an existing deploy.
- `POST /organizations/{organizationId}/deployments/{deploymentId}/deploys/{deployId}/finalize` to finalize a deploy.
- `POST /organizations/{organizationId}/deployments/{deploymentId}/deploys/{deployId}/rollback` to roll back a deploy.
New object schemas:
- `CreateDeployRequest`
- `Deploy`
- `DeploysPaginated`
- `FinalizeDeployRequest`
- `UpdateDeployRequest`
- `DeployRollbackRequest`
# April 23, 2024
- The endpoint `POST /organizations/{organizationId}/deployments` now accepts an `isDevelopmentMode` query parameter
# April 12, 2024
- You can now make requests to the [`Roles` endpoint](https://www.astronomer.io/docs/api/iam-api-reference/role/list-role-templates) to manage [custom roles](https://www.astronomer.io/docs/astro/customize-deployment-roles) in your Organization.
- The endpoint `GET /organizations/{organizationId}/clusters` now accepts a `names` query parameter
- The endpoint `GET /organizations/{organizationId}/deploymentss` now accepts a `names` query parameter
- The endpoint `GET /organizations/{organizationId}/workspaces` now accepts a `names` query parameter
# List authorization permission groups
```http
GET https://api.astronomer.io/iam/v1beta1/authorization/permission-groups
```
List the available permissions you can grant to a custom role.
## Query Parameters
- ScopeType (optional): Filter the returned permissions based on the scope they apply to. Note that currently, the only available permissions are in the `DEPLOYMENT` scope.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/iam/v1beta1/authorization/permission-groups \
-H "Authorization: Bearer "
```
# List allowed IP address ranges
```http
GET https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/allowed-ip-address-ranges
```
List allowed IP address ranges.
## Path Parameters
- OrganizationId (required): The ID of the Organization that you want to retrieve the list of IP addresses for.
## Query Parameters
- Offset (optional): The number of results to skip before returning values.
- Limit (optional): The maximum number of results to return.
- Sorts (optional): A list of field names to sort by, and whether to show results as ascending or descending. Formatted as `:asc` or `:desc`.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/iam/v1beta1/organizations/organizationId/allowed-ip-address-ranges \
-H "Authorization: Bearer "
```
# Create an allowed IP address range
```http
POST https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/allowed-ip-address-ranges
Content-Type: application/json
```
Create an allowed IP address range that constrains which IP addresses can be used to interact with your Astro Organization using APIs.
## Path Parameters
- OrganizationId (required): The ID of the Organization where you want to create the allowed IP address range.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/organizationId/allowed-ip-address-ranges \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"ipAddressRange": "1.1.1.1/32"
}'
```
# Delete an allowed IP address range
```http
DELETE https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/allowed-ip-address-ranges/{allowedIpAddressRangeId}
```
Delete an allowed IP address range.
## Path Parameters
- OrganizationId (required): The ID of the Organization where you want to delete the allowed IP address range.
- AllowedIpAddressRangeId (required): The ID of the allowed IP address range that you want to delete.
## Response Body
- 204:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X DELETE https://api.astronomer.io/iam/v1beta1/organizations/organizationId/allowed-ip-address-ranges/allowedIpAddressRangeId \
-H "Authorization: Bearer "
```
# Create a user invitation
```http
POST https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/invites
Content-Type: application/json
```
Invite a user to an Organization.
## Path Parameters
- OrganizationId (required): The ID of the Organization to invite the user to.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/organizationId/invites \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"inviteeEmail": "user1@company.com",
"role": "ORGANIZATION_MEMBER"
}'
```
# Delete a user invite
```http
DELETE https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/invites/{inviteId}
```
Delete an existing user invite.
## Path Parameters
- OrganizationId (required): The ID of the Organization where the user was invited to.
- InviteId (required): The invite's ID.
## Response Body
- 204:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X DELETE https://api.astronomer.io/iam/v1beta1/organizations/organizationId/invites/inviteId \
-H "Authorization: Bearer "
```
# Get role templates
```http
GET https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/role-templates
```
Get a list of available role templates in an Organization. A role template can be used as the basis for creating a new custom role.
## Path Parameters
- OrganizationId (required): The Organization's ID.
## Query Parameters
- ScopeTypes (optional): Filter role templates based on the scope of permissions they include.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/iam/v1beta1/organizations/organizationId/role-templates \
-H "Authorization: Bearer "
```
# List roles
```http
GET https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/roles
```
List available user roles in an Organization.
## Path Parameters
- OrganizationId (required): The Organization's ID.
## Query Parameters
- IncludeDefaultRoles (optional): Whether to include default Astro roles in the returned list.
- ScopeTypes (optional): Filter the list of roles based on the scope of each role.
- Offset (optional): Offset for pagination.
- Limit (optional): Limit for pagination.
- Sorts (optional): Sorting criteria, each criterion should conform to format 'fieldName:asc' or 'fieldName:desc'.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/iam/v1beta1/organizations/organizationId/roles \
-H "Authorization: Bearer "
```
# Create a custom role
```http
POST https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/roles
Content-Type: application/json
```
Create a custom role that you can assign to users, Teams, and API tokens.
## Path Parameters
- OrganizationId (required): The ID of the Organization where you want to create the custom role.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/organizationId/roles \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"description": "Subject can only view deployments.",
"name": "Deployment_Viewer",
"permissions": [
"deployment.get"
],
"restrictedWorkspaceIds": [
"cldbvzoi20182g8odxt8ehi5i"
],
"scopeType": "DEPLOYMENT"
}'
```
# Update custom role
```http
POST https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/roles/{customRoleId}
Content-Type: application/json
```
Update the metadata or included permissions for a custom role.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the role belongs.
- CustomRoleId (required): The custom role's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/organizationId/roles/customRoleId \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"description": "Subject can only view deployments.",
"name": "Deployment_Viewer",
"permissions": [
"deployment.get"
],
"restrictedWorkspaceIds": [
"cldbvzoi20182g8odxt8ehi5i"
]
}'
```
# Delete a custom role
```http
DELETE https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/roles/{customRoleId}
```
Delete a custom role.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the role belongs.
- CustomRoleId (required): The ID of the role to delete.
## Response Body
- 204:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X DELETE https://api.astronomer.io/iam/v1beta1/organizations/organizationId/roles/customRoleId \
-H "Authorization: Bearer "
```
# Get a custom role
```http
GET https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/roles/{roleId}
```
Get details about a custom role.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the role belongs.
- RoleId (required): The role's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/iam/v1beta1/organizations/organizationId/roles/roleId \
-H "Authorization: Bearer "
```
# List Teams
```http
GET https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/teams
```
List all Teams in an Organization.
## Path Parameters
- OrganizationId (required): ID of the Organization to list Teams for.
## Query Parameters
- Names (optional): A list of names for Teams to filter by. The API returns details only for the specified Teams.
- Offset (optional): Offset for pagination
- Limit (optional): Limit for pagination
- Sorts (optional): Sorting criteria, each criterion should conform to format 'fieldName:asc' or 'fieldName:desc'
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/iam/v1beta1/organizations/organizationId/teams \
-H "Authorization: Bearer "
```
# Create a Team
```http
POST https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/teams
Content-Type: application/json
```
Create a Team in an Organization. A Team is a group of users that have the same set of permissions in an Organization or Workspace.
## Path Parameters
- OrganizationId (required): The ID of the Organization where the Team is created.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/organizationId/teams \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"description": "My Team description",
"memberIds": [
"clma67byh000008md1gr995ez"
],
"name": "My Team",
"organizationRole": "ORGANIZATION_MEMBER"
}'
```
# Get a Team
```http
GET https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/teams/{teamId}
```
Retrieve details about a specific Team.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Team belongs.
- TeamId (required): The ID of the Team to retrieve data for.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/iam/v1beta1/organizations/organizationId/teams/teamId \
-H "Authorization: Bearer "
```
# Update a Team
```http
POST https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/teams/{teamId}
Content-Type: application/json
```
Update a Team's details.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Team belongs.
- TeamId (required): The ID of the Team to update.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/organizationId/teams/teamId \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"description": "My Team Description",
"name": "My Team"
}'
```
# Delete a Team
```http
DELETE https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/teams/{teamId}
```
Delete a Team. Deleting a Team will remove all permissions associated with the Team. Users that previously belonged to the Team will no longer have these permissions.
## Path Parameters
- OrganizationId (required): The ID of the Organization to delete the Team from.
- TeamId (required): The ID of the Team to delete.
## Response Body
- 204:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X DELETE https://api.astronomer.io/iam/v1beta1/organizations/organizationId/teams/teamId \
-H "Authorization: Bearer "
```
# List Team members
```http
GET https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/teams/{teamId}/members
```
List the details about all users that belong to a specific Team.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Team belongs.
- TeamId (required): The ID of the Team to retrieve member information for.
## Query Parameters
- Offset (optional): Offset for pagination
- Limit (optional): Limit for pagination
- Sorts (optional): Sorting criteria, each criterion should conform to format 'fieldName:asc' or 'fieldName:desc'
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/iam/v1beta1/organizations/organizationId/teams/teamId/members \
-H "Authorization: Bearer "
```
# Add members to a team
```http
POST https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/teams/{teamId}/members
Content-Type: application/json
```
Add members to a team
## Path Parameters
- OrganizationId (required): organization ID
- TeamId (required): team ID
## Response Body
- 204:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/organizationId/teams/teamId/members \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"memberIds": [
"clma5y9hu000208k2aumf7pbd"
]
}'
```
# Remove Team member
```http
DELETE https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/teams/{teamId}/members/{memberId}
```
Remove a user from a Team. The user loses all permissions associated with the Team.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the user belongs.
- TeamId (required): The ID of the Team to remove the user from.
- MemberId (required): The ID of the user to remove.
## Response Body
- 204:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X DELETE https://api.astronomer.io/iam/v1beta1/organizations/organizationId/teams/teamId/members/memberId \
-H "Authorization: Bearer "
```
# Update Team roles
```http
POST https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/teams/{teamId}/roles
Content-Type: application/json
```
Update Organization and Workspace roles for a Team.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the Team belongs.
- TeamId (required): The ID of the Team to update roles for.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/organizationId/teams/teamId/roles \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"deploymentRoles": [
{
"deploymentId": "clm8t5u4q000008jq4qoc3031",
"role": "DEPLOYMENT_ADMIN"
}
],
"organizationRole": "ORGANIZATION_MEMBER",
"workspaceRoles": [
{
"role": "WORKSPACE_MEMBER",
"workspaceId": "clm8t5u4q000008jq4qoc3036"
}
]
}'
```
# List API tokens
```http
GET https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/tokens
```
List information about all API tokens from an Organization. Filters on Workspace when Workspace ID is provided. When `includeOnlyOrganizationTokens` is `true`, only Organization API tokens are returned.
## Path Parameters
- OrganizationId (required): The ID of the Organization to list tokens for.
## Query Parameters
- WorkspaceId (optional): The ID of the Workspace to list API tokens for.
- DeploymentId (optional): The ID of the Deployment to list API tokens for.
- IncludeOnlyOrganizationTokens (optional): Whether to show only Organization API tokens.
- Offset (optional): Offset for pagination
- Limit (optional): Limit for pagination
- Sorts (optional): Sorting criteria, each criterion should conform to format 'fieldName:asc' or 'fieldName:desc'
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/iam/v1beta1/organizations/organizationId/tokens \
-H "Authorization: Bearer "
```
# Create an API token
```http
POST https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/tokens
Content-Type: application/json
```
Create an API token. An API token is an alphanumeric token that grants programmatic access to Astro for automated workflows. An API token can be scoped to an Organization or a Workspace.
## Path Parameters
- OrganizationId (required): The ID of the Organization where you want to create the token.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/organizationId/tokens \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"description": "This is my API token",
"entityId": "clm8pxjjw000008l23jm08hyu",
"name": "My token",
"role": "WORKSPACE_OWNER",
"tokenExpiryPeriodInDays": 30,
"type": "WORKSPACE"
}'
```
# Get an API token
```http
GET https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/tokens/{tokenId}
```
Retrieve information about a specific API token.
## Path Parameters
- OrganizationId (required): The ID of the Organization where you want to retrieve token information.
- TokenId (required): The ID of the token that you want to retrieve data for.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/iam/v1beta1/organizations/organizationId/tokens/tokenId \
-H "Authorization: Bearer "
```
# Update an API token
```http
POST https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/tokens/{tokenId}
Content-Type: application/json
```
Update the name and description of an API token.
## Path Parameters
- OrganizationId (required): The ID of the Organization where you want to update an API token.
- TokenId (required): The API token you want to update.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/organizationId/tokens/tokenId \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"description": "This is my API token",
"name": "My token"
}'
```
# Delete an API token
```http
DELETE https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/tokens/{tokenId}
```
Delete an API token. When you delete an API token, make sure that no existing automation workflows are using it. After it's deleted, an API token cannot be recovered.
## Path Parameters
- OrganizationId (required): The ID of the Organization where you want to delete the token.
- TokenId (required): The API token ID
## Response Body
- 204:
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X DELETE https://api.astronomer.io/iam/v1beta1/organizations/organizationId/tokens/tokenId \
-H "Authorization: Bearer "
```
# Update API token roles
```http
POST https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/tokens/{tokenId}/roles
Content-Type: application/json
```
Update Workspace and Organization roles for an API token.
## Path Parameters
- OrganizationId (required): The ID of the Organization where you want to update an API token.
- TokenId (required): The API token you want to update.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/organizationId/tokens/tokenId/roles \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"roles": [
{
"entityId": "clm8sgvai000008l794psbkdv",
"entityType": "WORKSPACE",
"role": "WORKSPACE_MEMBER"
}
]
}'
```
# Rotate API token
```http
POST https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/tokens/{tokenId}/rotate
```
Rotate an API token. Creates a new API token and invalidates the one you specify. Any workflows using the previous value stop working.
## Path Parameters
- OrganizationId (required): The ID of the Organization where you want to rotate an API token.
- TokenId (required): The token to rotate
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/organizationId/tokens/tokenId/rotate \
-H "Authorization: Bearer "
```
# List users in an Organization
```http
GET https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/users
```
List users in an Organization or a specific Workspace or Deployment within an Organization. If you specify `workspaceId`, the response lists the user's Workspace and Organization roles. If you specify `deploymentId`, the response lists the user's Deployment and Organization roles. If you specify both `workspaceId` and `deploymentId`, the response lists Workspace, Deployment, and Organization roles for users that belong to both the specified Workspace and Deployment.
## Path Parameters
- OrganizationId (required): The ID of the Organization to list users for.
## Query Parameters
- WorkspaceId (optional): The ID of the Workspace to filter the list of users for. When specified, the API returns only users belonging to the specified Workspace.
- DeploymentId (optional): The ID of the Deployment to filter the list of users for. When specified, the API returns only users belonging to the specified Deployment.
- Offset (optional): Offset for pagination
- Limit (optional): Limit for pagination
- Sorts (optional): Sorting criteria, each criterion should conform to format 'fieldName:asc' or 'fieldName:desc'
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/iam/v1beta1/organizations/organizationId/users \
-H "Authorization: Bearer "
```
# Get user information
```http
GET https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/users/{userId}
```
Retrieve user information about a specific user account.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the user belongs.
- UserId (required): The user's ID.
## Response Body
- 200: OK
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl https://api.astronomer.io/iam/v1beta1/organizations/organizationId/users/userId \
-H "Authorization: Bearer "
```
# Update a user's roles
```http
POST https://api.astronomer.io/iam/v1beta1/organizations/{organizationId}/users/{userId}/roles
Content-Type: application/json
```
Update Organization and Workspace roles for a user.
## Path Parameters
- OrganizationId (required): The ID of the Organization to which the user belongs.
- UserId (required): The user's ID
## Response Body
- 200: The response body containing the user's roles
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
## Examples
```shell
curl -X POST https://api.astronomer.io/iam/v1beta1/organizations/organizationId/users/userId/roles \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"deploymentRoles": [
{
"deploymentId": "clm8t5u4q000008jq4qoc3031",
"role": "DEPLOYMENT_ADMIN"
}
],
"organizationRole": "ORGANIZATION_MEMBER",
"workspaceRoles": [
{
"role": "WORKSPACE_MEMBER",
"workspaceId": "clm8t5u4q000008jq4qoc3036"
}
]
}'
```
# December 10, 2024
## Summary
Added new RBAC roles for [Public Preview Astro Observe](https://www.astronomer.io/docs/astro/create-data-products).
## Added
Included the following new enums for defining Organization roles:
- `ORGANIZATION_OBSERVE_ADMIN`
- `ORGANIZATION_OBSERVE_MEMBER`
# July 31, 2024
## Summary
This update introduces new endpoints for managing IP access lists. See [Astro IP access list documentation](https://www.astronomer.io/docs/astro/ip-access-list) for more information.
### Added
New endpoints:
- `GET /organizations/{organizationId}/allowed-ip-address-ranges` to list allowed IP address ranges
- `POST /organizations/{organizationId}/allowed-ip-address-ranges` to create an allowed IP address range that constrains which IP addresses can be used to interact with your Astro Organization using APIs
- `DELETE /organizations/{organizationId}/allowed-ip-address-ranges/{allowedIpAddressRangeId}` to delete an allowed IP address range.
New object schemas:
- `CreateAllowedIpAddressRangeRequest`
- `AllowedIpAddressRangesPaginated`
- `AllowedIpAddressRange`
# April 12, 2024
- The endpoint `DELETE /organizations/{organizationId}/roles/{customRoleId}` now returns a
`deploymentRoles` attribute
- The endpoint `GET /authorization/permission-groups` now returns a
`deploymentRoles` attribute
- The endpoint `GET /organizations/{organizationId}/role-templates` now returns a
`deploymentRoles` attribute
- The endpoint `GET /organizations/{organizationId}/roles` now returns a
`deploymentRoles` attribute
- The endpoint `GET /organizations/{organizationId}/roles/{roleId}` now returns a
`deploymentRoles` attribute
- The endpoint `POST /organizations/{organizationId}/roles` now returns a
`deploymentRoles` attribute
- The endpoint `POST /organizations/{organizationId}/roles/{customRoleId}` now returns a
`deploymentRoles` attribute