Get started with 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.
An Organization API token with the Organization Owner role. Astronomer recommends that you create a new API token for this tutorial.
An Astro Workspace.
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 request, which means that you can programmatically retrieve an Organization ID. To retrieve the Organization ID through the API, run the following command:

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

If the command was successful, then you receive a response that begins similarly to the following:

{
  "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:

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

If the command succeeds, the API returns a list of Workspaces similar to the following:

{
  "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:

curl --location 'https://api.astronomer.io/v1/organizations/<your-organization-id>/workspaces?limit=20&sorts=updatedAt:asc' \
--header 'Authorization: Bearer <your-organization-api-token>'

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.

Run the following command to create a new Workspace API token:

curl --location 'https://api.astronomer.io/v1/organizations/<your-organization-id>/tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your-organization-api-token>' \
--data '{
    "description": "I wrote this description using the Astro API!",
    "entityId": "<your-workspace-id>",
    "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.

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 v1

API Reference

Get started with the Astro API

Prerequisites

Step 1: Make your first API request

Step 2: Request Workspace details from the API

Step 3: Update your token description using the API

​Prerequisites

​Step 1: Make your first API request

​Step 2: Request Workspace details from the API

​Step 3: Update your token description using the API

Prerequisites

Step 1: Make your first API request

Step 2: Request Workspace details from the API

Step 3: Update your token description using the API