Houston API

The Astronomer Houston API is the source of truth across the entire Astronomer platform. For Astronomer Software users, our API is an easy way to do any of the following:

Query the platform’s database for information about a user, Workspace, or Deployment
Perform CRUD operations on entities scoped to the Astronomer platform, including Airflow Deployments, Workspaces, and users

For example, you can:

Delete a deployment
Look up a deployment’s resource config
Add a user to a Workspace
Make a user a System Administrator

Anything you can do with the Software UI, you can do programmatically with the Astronomer Houston API.

If you’re using the Astronomer Houston API and you’re migrating from Astronomer Certified (AC) to Astro Runtime, you’ll need to replaceairflowVersionarguments withruntimeVersionarguments in your scripts. For more information about migrating a Deployment from Astronomer Certified to Astro Runtime, seeMigrate a Deployment from Astronomer Certified to Astro Runtime.

Getting started

A GraphQL Playground is a graphical, interactive, in-browser GraphQL IDE where you can develop and test API queries. GraphQL itself is an open source query language for APIs that makes for an easy and simple way to manage data. For more information about the Playground features applicable to the wider GraphQL community, see GraphQL Playground’s Github. In short, the Playground is a portal that allows you to write GraphQL queries directly against the API within your browser. The Astronomer Houston API is available in two GraphQL Playgrounds, one requires an external connection to load visual assets, and a second option for use with airgapped environments.

Configure airgapped GraphQL playground access

Astronomer provides a GraphQL playground using an Apollo GraphQL Playground, accessed at https://houston.<your-base-domain>/v1/. The playground makes external requests to load assets such as JavaScript, CSS, and other resources from external URLs. As a result, it cannot be used in an airgapped environment or in cases where strict security requirements apply. By default, users can access both playgrounds. However, you can restrict users from using the GraphQL playground available at https://houston.<your-base-domain>/v1/. To disable access to the Apollo GraphQL Playground, and permit users to access only the GraphQL IDE at https://houston.<your-base-domain>/v1/playground, set the graphqlPlaygroundEnabled feature flag to false in your Houston API configuration in the config.yaml file:

astronomer:
  houston:
    config:
      graphqlPlaygroundEnabled: false

Then, apply a configuration change.

Access the GraphQL playground

The URL at which you can reach Houston’s GraphQL playground depends on the platform you’re running. For your installation of Astronomer, it will be https://houston.<your-base-domain>/v1/, or https://houston.<your-base-domain>/v1/playground for airgapped environments. For example, if you’re a Software customer and your basedomain is Astronomer, you would navigate to https://houston.astronomer/v1/ or https://houston.astronomer/v1/playground.

Authenticate

To query the Astronomer Houston API, you must first authenticate as an Astronomer user.

Go to https://app.BASEDOMAIN/token and copy the API token. Alternatively, note the API Key of a service account.
Open Astronomer’s Houston API GraphQL Playground at https://houston.<your-base-domain>/v1/ or https://houston.<your-base-domain>/v1/playground.
Expand the HTTP Headers section on the bottom left of the page.
Paste the API token you acquired from Step 1 in the following format: {"authorization": "<api-token>"}

As you work with our API, you’ll be restricted to actions allowed by both your existing role within the platform (e.g. SysAdmin or not) and your permissions within any particular Workspace (e.g. Viewer, Editor, Admin).

Query types

On Astronomer, you can ask for GraphQL:

Queries - Queries to return information
Mutations - Queries to modify data

Houston API schema

Once authenticated, you should be able to query all endpoints your user has access to. The Schema tab fixed on the right-hand side of the page is a great reference for queries and mutations we support and how each of them is structured. Schema

Sample queries

Read below for commonly used queries. For those not in this doc, reference the “Schema” on the right-hand side as referenced above.

Query an Airflow Deployment

The workspaceDeployments query requires the following inputs:

workspaceUuid
releaseName

and can return any of the fields under Type Details:

config
uuid
status
createdAt
updatedAt
roleBindings
etc.

For instance, you can run the following:

query workspaceDeployments {
  workspaceDeployments(
    releaseName: "mathematical-probe-2087"
    workspaceUuid: "ck35y9uf44y8l0a19cmwd1x8x"
  )
  {
    config
    uuid
    status
    createdAt
    updatedAt
    workspace {users {emails {address, createdAt} }}
  }
}

To view results, press the “Play” button in middle of the page and see them render on the right side of the page. Query

Query a user

To query for information about a user on the platform (e.g. “When was this user created?” “Does this user exist?” “What roles do they have on any Workspace?”), run a variation of the following:

query User {
  users(user: { email: "<name@example.com>"} )
  {
    id
    roleBindings {role}
    status
    createdAt
  }
}

In the output, you should see:

The user’s id
A list of existing roles across the cluster (e.g. Workspace Admin)
The status of the user (active, pending)
A timestamp that reflects when the user was created

Sample mutations

Mutations make a change to your platform’s underlying database. For some common examples, read below.

Create a Deployment

To create a Deployment, you’ll need:

Workspace Admin permissions
Your Workspace ID

Then, to create a Deployment, run the following:

mutation CreateDeployment {
  createDeployment(
    workspaceUuid: "<workspace-id>",
    type: "airflow",
    label: "<deployment-name>",
    config: {executor:"<airflow-executor>"},

    )
    {
      id
      config
      releaseName
      workspace{label}
      roleBindings{id}
    }
}

Here, <airflow-executor> can be LocalExecutor, CeleryExecutor, or KubernetesExecutor.

Create or update a Deployment with configurations

The upsertDeployment mutation is behind a feature flag. To enable this feature, set the following configuration in your values.yaml file:

astronomer:
  houston:
    config:
      deployments:
        upsertDeploymentEnabled: true

Then push the configuration change to your cluster. See Apply a config change.

The upsertDeployment mutation can be used to both create and update Deployments with all possible Deployment configurations. If you query upsertDeployment without a deploymentUuid, the Houston API creates a new Deployment according to your specifications. If you specify an existing deploymentUuid, the Houston API updates the Deployment with that ID. All queries to create a Deployment require specifying a workspaceUuid.

When you make upsert updates to your Airflow Deployments, you must explicitly specify all existing environment variables, otherwise, the upsert overwrites them.

The following query creates a new Deployment in a custom namespace test-new-dep and configures a Deployment environment variable AIRFLOW__CORE__COLORED_LOG_FORMAT.

mutation upsertDeployment(
  $workspaceUuid: Uuid,
  $deploymentUuid: Uuid,
  $label: String,
  $description: String,
  $releaseName: String,
  $namespace: String,
  $environmentVariables: [InputEnvironmentVariable],
  $image: String,
  $dockerconfigjson: JSON,
  $version: String,
  $airflowVersion: String,
  $runtimeVersion: String,
  $desiredRuntimeVersion: String,
  $executor: ExecutorType,
  $workers: Workers,
  $webserver: Webserver,
  $scheduler: Scheduler,
  $triggerer: Triggerer,
  $dagDeployment: DagDeployment,
  $properties: JSON,
  $cloudRole: String
) {
  upsertDeployment(
    workspaceUuid: $workspaceUuid,
    deploymentUuid: $deploymentUuid,
    label: $label,
    description: $description,
    releaseName: $releaseName,
    namespace: $namespace,
    environmentVariables: $environmentVariables,
    image: $image,
    dockerconfigjson: $dockerconfigjson,
    version: $version,
    airflowVersion: $airflowVersion,
    runtimeVersion: $runtimeVersion,
    desiredRuntimeVersion: $desiredRuntimeVersion,
    executor: $executor,
    workers: $workers,
    webserver: $webserver,
    scheduler: $scheduler,
    triggerer: $triggerer,
    dagDeployment: $dagDeployment,
    properties: $properties,
    cloudRole: $cloudRole
) {
    id
    config
    urls {
      type
      url
      __typename
    }
    properties
    description
    label
    releaseName
    namespace
    status
    type
    version
    workspace {
      id
      label
      __typename
    }
    airflowVersion
    runtimeVersion
    desiredAirflowVersion
    upsertedEnvironmentVariables {
      key
      value
      isSecret
      __typename
    }
    dagDeployment {
      type
      nfsLocation
      repositoryUrl
      branchName
      syncInterval
      syncTimeout
      ephemeralStorage
      dagDirectoryLocation
      rev
      sshKey
      knownHosts
      __typename
    }
    createdAt
    updatedAt
    __typename
  }
}
{
  "workspaceUuid": "cldemxl9502454yxe6vjlxy23",
	"environmentVariables": [
    {
      "key": "AIRFLOW__CORE__COLORED_LOG_FORMAT",
      "value": "test",
      "isSecret": false
    }
  ],
  "releaseName": "",
  "namespace": "test-new-dep",
  "executor": "CeleryExecutor",
  "workers": {},
  "webserver": {},
  "scheduler": {
    "replicas": 1
  },
  "label": "test-new-dep",
  "description": "",
  "runtimeVersion": "7.2.0",
  "properties": {
    "extra_au": 0
  },
  "dagDeployment": {
    "type": "image",
    "nfsLocation": "",
    "repositoryUrl": "",
    "branchName": "",
    "syncInterval": 1,
    "syncTimeout": 120,
    "ephemeralStorage": 2,
    "dagDirectoryLocation": "",
    "rev": "",
    "sshKey": "",
    "knownHosts": ""
  }
}

Delete a Deployment

To delete a Deployment, you’ll need:

Permission (SysAdmin or Workspace Admin)
A Deployment ID

For more information about the SysAdmin role, reference our “User Management” doc.

If you don’t have a Deployment ID, run astro deployment list in the Astro CLI or follow the steps in “Query an Airflow Deployment”. Then, to delete a Deployment, run the following:

mutation DeleteDeployment {
  deleteDeployment (
    deploymentUuid: "<deployment-id>"
  ) {
    uuid
  }
}

Create a Deployment user

To create a Deployment user, you’ll need:

Workspace Admin privileges
A Deployment ID

If you don’t have a Deployment ID, run astro deployment list in the Astro CLI or follow the steps in “Query an Airflow Deployment”. First, add the following to your GraphQL playground:

mutation AddDeploymentUser(
		$userId: Id
		$email: String!
		$deploymentId: Id!
		$role: Role!
	) {
		deploymentAddUserRole(
			userId: $userId
			email: $email
			deploymentId: $deploymentId
			role: $role
		) {
			id
			user {
				username
			}
			role
			deployment {
				id
				releaseName
			}
		}
	}

Then, in the Query Variables tab, add the following:

{
  "role": "<user-role>",
  "deploymentId": "<deploymentId>",
  "email": "<email-address>"
}

Here, <user-role> can be DEPLOYMENT_ADMIN, DEPLOYMENT_EDITOR, or DEPLOYMENT_VIEWER. After you specify these variables, run the mutation.

Delete a user

To delete a user, you’ll need:

SysAdmin permissions
userUuid

With a userUuid, run the following:

mutation removeUser {
	removeUser (
    userUuid: "<USERUUID>"
  ) {
    uuid
    emails {address}
    status
  }
}

Verify user email

If a user on the platform has trouble verifying their email address upon signup, you can use the Playground to manually verify it. To run this mutation, you’ll need:

SysAdmin Permissions
User’s email address

With the email address in question, run the following:

mutation verifyEmail {
	verifyEmail (
    email: "<USERUUID>"
  )
}

To run this mutation, ensure that the user in question has already begun creating an account on the platform (i.e. the user has signed up and the platform has generated an “invite token” for that user).

Bypass user email verification

If you don’t need certain users to verify their email before joining a Workspace, you can configure a bypass when adding them to a Workspace. This can be useful for minimizing friction when programmatically inviting many users to your platform. To run this mutation, you’ll need:

Workspace Admin permissions
A Workspace ID
The user’s email address
The user’s Workspace role

mutation workspaceAddUser(
    $workspaceUuid: Uuid = "<your-workspace-uuid>"
    $email: String! = "<user-email-address>"
    $role: Role! = <user-workspace-role>
    $bypassInvite: Boolean! = true
  ) {
    workspaceAddUser(
      workspaceUuid: $workspaceUuid
      email: $email
      role: $role
      deploymentRoles: $deploymentRoles
      bypassInvite: $bypassInvite
    ) {
      id
    }
  }

Add a System Admin (Software only)

System Admins can be added either via the Software UI (‘System Admin’ > ‘User’ > ‘User Details’) or via an API call to Houston. To run the mutation in the GraphQL Playground, you’ll need:

userUuid
role (SYSTEM_ADMIN)

Keep in mind that only existing System Admins can grant the SysAdmin role to another user and that the user in question must already have a verified email address and already exist in the system.

With the uuid you pulled above, call the createSystemRoleBinding mutation by running:

mutation AddAdmin {
  createSystemRoleBinding(
    userId: "<uuid>"
    role: SYSTEM_ADMIN
  ) {
    id
  }
}

If you’re assigning a user a different System-Level Role, replace SYSTEM_ADMIN with either SYSTEM_VIEWER or SYSTEM_EDITOR in the mutation above.

Create a service account

You can create Deployment and Workspace-level accounts in the Software UI as described in Deploy to Astronomer via CI/CD. Alternatively, you can create platform-level service accounts programmatically via the Houston API. To create a service account via the Houston API, run the following in your GraphQL Playground:

mutation CreateSystemServiceAccount {
  createSystemServiceAccount(label: "<label>", role: SYSTEM_ADMIN) {
     apiKey
     id
  }
}

Update environment variables

To programmatically update environment variables, you’ll need:

A Deployment ID
A Deployment release name

If you don’t have a Deployment ID, run astro deployment list in the Astro CLI or follow the steps in “Query an Airflow Deployment”. Then, in your GraphQL Playground, run the following:

mutation UpdateDeploymentVariables {
  updateDeploymentVariables(
    deploymentUuid: "<deployment-id>",
  	releaseName: "<deployment-release-name>",
    environmentVariables: [
      {key: "<environment-variable-1>",
      value: "<environment-variable-value-1>",
      isSecret: <true-or-false>},
      {key: "<environment-variable-2>",
      value: "<environment-variable-value-2>",
      isSecret: <true-or-false>}
    ]
  ) {
    key
    value
    isSecret
  }
}

Custom types

Any object in the Schema that maps to a custom GraphQL Type often requires additional subfields to be added to the query or mutation return object. Below, we describe this concept in the context of a sample mutation.

Add a user to a Workspace

For example, take the “Add a user to a Workspace” mutation. As input, you need:

A Workspace ID
Email address of the user
The designated role for the user (for example,. Workspace “Admin”, “Editor” or “Viewer”)

If you don’t already have a Workspace ID, run astro workspace list in the Astro CLI. With that information, run the following:

mutation WorkspaceAddUser {
	workspaceAddUser (
    workspaceUuid: "<workspace-id>"
    email: "<email@example.com>"
    role: WORKSPACE_ADMIN
  ) {
    users {emails {address} }
    label
    createdAt
  }
}

In the above example, you should see the following return:

The email addresses of all users in the Workspace
The Workspace label
The date on which the Workspace was created

Unlike the label and createdAt fields, notice that the users type field requires you to specify additional subfields, i.e. emails and then addresses. To know which fields you can or must specify, reference the “Schema” on the righthand side of the page. As is the case here, custom types are often composed of other custom types.

Delete a Workspace

To delete a Workspace, you’ll need the ID of the Workspace you want to delete. You can find this by running astro workspace list. Using the Workspace ID, run the following query to delete the Workspace:

mutation deleteWorkspace(
    $workspaceUuid: Uuid = "<workspace-id>"
  ) {
    deleteWorkspace(
      workspaceUuid: $workspaceUuid
    ) {
        id
    }
  }

v0.37

v0.36

v0.34

Reference

Getting started

Configure airgapped GraphQL playground access

Access the GraphQL playground

Authenticate

Query types

Houston API schema

Sample queries

Query an Airflow Deployment

Query a user

Sample mutations

Create a Deployment

Create or update a Deployment with configurations

Delete a Deployment

Create a Deployment user

Delete a user

Verify user email

Bypass user email verification

Add a System Admin (Software only)

Create a service account

Update environment variables

Custom types

Add a user to a Workspace

Delete a Workspace

v0.37

v0.36

v0.34

Reference

Documentation Index

​Getting started

​Configure airgapped GraphQL playground access

​Access the GraphQL playground

​Authenticate

​Query types

​Houston API schema

​Sample queries

​Query an Airflow Deployment

​Query a user

​Sample mutations

​Create a Deployment

​Create or update a Deployment with configurations

​Delete a Deployment

​Create a Deployment user

​Delete a user

​Verify user email

​Bypass user email verification

​Add a System Admin (Software only)

​Create a service account

​Update environment variables

​Custom types

​Add a user to a Workspace

​Delete a Workspace

Getting started

Configure airgapped GraphQL playground access

Access the GraphQL playground

Authenticate

Query types

Houston API schema

Sample queries

Query an Airflow Deployment

Query a user

Sample mutations

Create a Deployment

Create or update a Deployment with configurations

Delete a Deployment

Create a Deployment user

Delete a user

Verify user email

Bypass user email verification

Add a System Admin (Software only)

Create a service account

Update environment variables

Custom types

Add a user to a Workspace

Delete a Workspace