Skip to main content

Documentation Index

Fetch the complete documentation index at: https://astronomer-preview.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Use the following example Houston API requests as the basis for the applications you develop for Astronomer Software.

​
Example queries

You can retrieve common information for specific Astronomer objects by using the following sample queries.

​
Finding the id of a workspace you belong to [#workspaces]

Use the workspaces query to find the ID of a Workspace that you belong to. Optionally, you can choose to filter by Deployment label. 
query {
  workspaces(label:"example-workspace") {
    id,
    label
  }
}

​
Finding the id of all workspaces [#sysWorkspaces]

System administrators can use the sysWorkspaces query to perform a bulk-fetch of all Workspaces and their respective IDs using the sysWorkspaces query. After retrieving the full list, you can filter the Workspaces within your application to locate the ID corresponding to the label of interest. 
query {
  sysWorkspaces {
    id,
    label
  }
}

​
Query Deployment details

You can use the workspaceDeployment query to retrieve details about a Deployment in a given Workspace. It requires the following inputs:
  • Workspace ID: To retrieve this value, use the sysWorkspaces or workspaces query, or run astro workspace list. Alternatively, open a Workspace in the Software UI and copy the value after /w/ in your Workspace URL, for example, https://app.basedomain/w/<workspace-id>.
  • Deployment release name: To retrieve this value, run astro deployment list in your Workspace. Alternatively, you can copy the Release name from your Deployment’s Settings tab in the Software UI.
The workspaceDeployment query can return also any of the fields under Type Details, such as:
  • config
  • uuid
  • status
  • createdAt
  • updatedAt
  • roleBindings
For example, you can run the following query to retrieve the Deployment’s:
  • ID
  • Health status
  • Creation time
  • Update time
  • Users
query workspaceDeployment {
  workspaceDeployment(
    releaseName: "mathematical-probe-2087"
    workspaceUuid: "ck35y9uf44y8l0a19cmwd1x8x"
  )
  {
    id
    status
    createdAt
    updatedAt
    roleBindings {
      id,
      role,
      user {
        username,
        emails {
          primary
        }
      }
    }
  }
}

​
Query user details

A common query is users, which lets you retrieve information about multiple users at once. To use this query, you must provide:
  • At least one of the following userSearch values:
    • userId (String): The user’s ID
    • userUuid(String): The user’s unique ID
    • username (String): The user’s username
    • email (String): The user’s email
    • fullName (String): The user’s full name
    • createdAt(DateTime): When the user was created
    • updatedAt(DateTime): When the user was updated
  • Workspace ID: To retrieve this value, run astro workspace list. Alternatively, open a Workspace in the Software UI and copy the value after /w/ in your Workspace URL, for example https://app.basedomain/w/<workspace-id>.
The query returns the requested details for all users who exactly match the values provided for the userSearch. For example, the following query would retrieve the requested values for any user accounts with the email name@mycompany.com: 
query User {
  users(user: { email: "<name@mycompany.com>"} )
  {
    id
    roleBindings {role}
    status
    createdAt
  }
}

​
Example mutations

Mutations make a change to your platform’s underlying database. The following sections describe some common examples.

​
Create a Deployment

To create a Deployment, you need Workspace Admin permissions and a Workspace ID. To retrieve this value, run astro workspace list. Alternatively, open a Workspace in the Software UI and copy the value after /w/ in your Workspace URL, for example https://app.basedomain/w/<workspace-id>. This example mutation creates a Deployment with the Celery executor and the latest Runtime version. It then returns the Deployment’s ID and configuration to confirm that it was successfully created. 
mutation CreateNewDeployment{
  createDeployment(
    workspaceUuid: "<workspace-id>",
    type: "airflow",
    label: "<deployment-name>",
    executor:CeleryExecutor,
    runtimeVersion: "13.2.0"
  ) {
  id
  }
}

​
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 config.yaml file:
astronomer:
  houston:
    config:
      deployments:
        upsertDeploymentEnabled: true
Then push the configuration change to your cluster. See Apply a config change.
You can use the upsertDeployment mutation 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,
  $dagProcessor: DagProcessor,
  $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,
    dagProcessor: $dagProcessor,
    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
  },
  "dagProcessor": {},
  "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 need:
  • Either System Admin or Workspace Admin permissions
  • A Deployment ID. To retrieve this value, run astro deployment list or request the id value in the workspaceDeployment query.
The following example mutation deletes a Deployment, then returns the ID of the Deployment to confirm that it was successfully deleted. 
mutation DeleteDeployment {
  deleteDeployment (
    deploymentUuid: "<deployment-id>"
  ) {
    id
  }
}

​
Create a Deployment user

To add an existing Astronomer Software user to a Deployment, you need:
  • Workspace Admin privileges
  • A Deployment ID. To retrieve this value, run astro deployment list or request the id value in the workspaceDeployment query.
  • The ID of the user to add. To retrieve this, request the id value in a users query or run astro workspace user list.
  • The role to add the user as. Can be DEPLOYMENT_ADMIN, DEPLOYMENT_EDITOR, or DEPLOYMENT_VIEWER.
The following query adds a user to a Deployment as a Deployment viewer, then returns the user and Deployment information back to the requester. 
mutation AddDeploymentUser(
  $userId: Id! = "f9182b1d-2f7c-4d33-920b-2124b1660d83",
  $email: String! = "usertoadd@mycompany.com",
  $deploymentId: Id! = "<some_id>",
  $role: Role! = DEPLOYMENT_VIEWER
)
{
		deploymentAddUserRole(
			userId: $userId
			email: $email
			deploymentId: $deploymentId
			role: $role
		) {
			id
			user {
				username
			}
			role
			deployment {
				id
				releaseName
			}
		}
	}

​
Delete a user

To delete a user from Astronomer Software, you need:
  • System Admin permissions
  • The ID of the user to delete. To retrieve this, request the id value in a users query or run astro workspace user list.
The following query removes a user, then returns information about the deleted user. 
mutation removeUser {
	removeUser (
    id: "<user-id>"
  ) {
    uuid
    emails {address}
    status
  }
}

​
Verify user email

If a user on the platform has trouble verifying their email address, you can use the Houston API to manually verify it for them. To run this mutation, you’ll need:
  • System Admin Permissions
  • The user’s email address. This needs to be the email address that the user provided when they began creating an account on the platform. They must have signed up for an account, and Astronomer Software must already have generated an invite token for the user.
The following request verifies the email and returns true or false based on whether the mutation was successful. 
mutation verifyEmail {
	verifyEmail (
    email: "<user-email>"
  )
}

​
Bypass user email verification

If you don’t need certain users to verify their email before they join a Workspace, you can configure a bypass when you add them to a Workspace. This can be useful for minimizing friction when programmatically inviting many users to your platform. To run this mutation, you need:
  • Workspace Admin permissions
  • A Workspace ID. To retrieve this value, run astro workspace list. Alternatively, open a Workspace in the Software UI and copy the value after /w/ in your Workspace URL (for example https://app.basedomain/w/<workspace-id>).
  • The user’s email address.
  • The user’s desired role in the Workspace (WORKSPACE_VIEWER, WORKSPACE_EDITOR, WORKSPACE_ADMIN).
The following example mutation can be run to add a user to a Workspace as a WORKSPACE_VIEWER. 
mutation workspaceAddUser(
    $workspaceUuid: Uuid = "<your-workspace-uuid>"
    $email: String! = "<user-email-address>"
    $role: Role! = WORKSPACE_VIEWER
    $bypassInvite: Boolean! = true
  ) {
    workspaceAddUser(
      workspaceUuid: $workspaceUuid
      email: $email
      role: $role
      bypassInvite: $bypassInvite
    ) {
      id
    }
  }

​
Add a System Admin

To add a user as a System Admin through the Houston API, you need the following values:
  • The user’s ID. To retrieve this, request the id value in a users query or run astro workspace user list.
  • System Admin permissions.
You can then run the following query to add the user as a System Admin. 
mutation createSystemRoleBinding (
    $userId: ID! = "<user-id>"
    $role: Role! = SYSTEM_ADMIN
) {
  createSystemRoleBinding(
    userId: $userId
    role: $role
  ) {
    id
  }
}

​
Create a System Service Account Token

System administrators can create a global system service account token to integrate with external systems, such as CI/CD pipelines. Use the following example mutation to create the service account token: 
mutation systemSACreate {
  createSystemServiceAccount(
    label: "your-sa"
    role: SYSTEM_ADMIN
  ) {
    id
    apiKey
  }
}
Save a copy of the returned API key value in a secure place as it won’t be displayed again.

​
Update environment variables

To programmatically update environment variables, you need:
  • A Deployment ID. To retrieve this value, run astro deployment list or request the id value in the workspaceDeployment query.
  • A Deployment release name: To retrieve this value, run astro deployment list in your Workspace. Alternatively, you can copy the Release name from your Deployment’s Settings tab in the Software UI.
Then, in your GraphQL Playground, run the following: 
mutation UpdateDeploymentVariables {
  updateDeploymentVariables(
    deploymentUuid: ID! = "<deployment-id>",
  	releaseName: String! = "<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
  }
}