Example Houston API requests

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

Use the workspaces query to find the ID of a Workspace that you belong to. Optionally, you can choose to filter by Deployment label.

1
query {
2
  workspaces(label:"example-workspace") {
3
    id,
4
    label
5
  }
6
}

Finding the id of all workspaces

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.

1
query {
2
  sysWorkspaces {
3
    id,
4
    label
5
  }
6
}

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

1
query workspaceDeployment {
2
  workspaceDeployment(
3
    releaseName: "mathematical-probe-2087"
4
    workspaceUuid: "ck35y9uf44y8l0a19cmwd1x8x"
5
  )
6
  {
7
    id
8
    status
9
    createdAt
10
    updatedAt
11
    roleBindings {
12
      id,
13
      role,
14
      user {
15
        username,
16
        emails {
17
          primary
18
        }
19
      }
20
    }
21
  }
22
}

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:

1
query User {
2
  users(user: { email: "<name@mycompany.com>"} )
3
  {
4
    id
5
    roleBindings {role}
6
    status
7
    createdAt
8
  }
9
}

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.

1
mutation CreateNewDeployment{
2
  createDeployment(
3
    workspaceUuid: "<workspace-id>",
4
    type: "airflow",
5
    label: "<deployment-name>",
6
    executor:CeleryExecutor,
7
    runtimeVersion: "13.2.0"
8
  ) {
9
  id
10
  }
11
}

Create or update a Deployment with configurations

1
astronomer:
2
  houston:
3
    config:
4
      deployments:
5
        upsertDeploymentEnabled: true

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.

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.

1
mutation upsertDeployment(
2
  $workspaceUuid: Uuid,
3
  $deploymentUuid: Uuid,
4
  $label: String,
5
  $description: String,
6
  $releaseName: String,
7
  $namespace: String,
8
  $environmentVariables: [InputEnvironmentVariable],
9
  $image: String,
10
  $dockerconfigjson: JSON,
11
  $version: String,
12
  $airflowVersion: String,
13
  $runtimeVersion: String,
14
  $desiredRuntimeVersion: String,
15
  $executor: ExecutorType,
16
  $workers: Workers,
17
  $webserver: Webserver,
18
  $scheduler: Scheduler,
19
  $triggerer: Triggerer,
20
  $dagDeployment: DagDeployment,
21
  $properties: JSON,
22
  $cloudRole: String
23
) {
24
  upsertDeployment(
25
    workspaceUuid: $workspaceUuid,
26
    deploymentUuid: $deploymentUuid,
27
    label: $label,
28
    description: $description,
29
    releaseName: $releaseName,
30
    namespace: $namespace,
31
    environmentVariables: $environmentVariables,
32
    image: $image,
33
    dockerconfigjson: $dockerconfigjson,
34
    version: $version,
35
    airflowVersion: $airflowVersion,
36
    runtimeVersion: $runtimeVersion,
37
    desiredRuntimeVersion: $desiredRuntimeVersion,
38
    executor: $executor,
39
    workers: $workers,
40
    webserver: $webserver,
41
    scheduler: $scheduler,
42
    triggerer: $triggerer,
43
    dagDeployment: $dagDeployment,
44
    properties: $properties,
45
    cloudRole: $cloudRole
46
) {
47
    id
48
    config
49
    urls {
50
      type
51
      url
52
      __typename
53
    }
54
    properties
55
    description
56
    label
57
    releaseName
58
    namespace
59
    status
60
    type
61
    version
62
    workspace {
63
      id
64
      label
65
      __typename
66
    }
67
    airflowVersion
68
    runtimeVersion
69
    desiredAirflowVersion
70
    upsertedEnvironmentVariables {
71
      key
72
      value
73
      isSecret
74
      __typename
75
    }
76
    dagDeployment {
77
      type
78
      nfsLocation
79
      repositoryUrl
80
      branchName
81
      syncInterval
82
      syncTimeout
83
      ephemeralStorage
84
      dagDirectoryLocation
85
      rev
86
      sshKey
87
      knownHosts
88
      __typename
89
    }
90
    createdAt
91
    updatedAt
92
    __typename
93
  }
94
}
95
{
96
  "workspaceUuid": "cldemxl9502454yxe6vjlxy23",
97
	"environmentVariables": [
98
    {
99
      "key": "AIRFLOW__CORE__COLORED_LOG_FORMAT",
100
      "value": "test",
101
      "isSecret": false
102
    }
103
  ],
104
  "releaseName": "",
105
  "namespace": "test-new-dep",
106
  "executor": "CeleryExecutor",
107
  "workers": {},
108
  "webserver": {},
109
  "scheduler": {
110
    "replicas": 1
111
  },
112
  "label": "test-new-dep",
113
  "description": "",
114
  "runtimeVersion": "7.2.0",
115
  "properties": {
116
    "extra_au": 0
117
  },
118
  "dagDeployment": {
119
    "type": "image",
120
    "nfsLocation": "",
121
    "repositoryUrl": "",
122
    "branchName": "",
123
    "syncInterval": 1,
124
    "syncTimeout": 120,
125
    "ephemeralStorage": 2,
126
    "dagDirectoryLocation": "",
127
    "rev": "",
128
    "sshKey": "",
129
    "knownHosts": ""
130
  }
131
}

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.

1
mutation DeleteDeployment {
2
  deleteDeployment (
3
    deploymentUuid: "<deployment-id>"
4
  ) {
5
    id
6
  }
7
}

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.

1
mutation AddDeploymentUser(
2
  $userId: Id! = "f9182b1d-2f7c-4d33-920b-2124b1660d83",
3
  $email: String! = "usertoadd@mycompany.com",
4
  $deploymentId: Id! = "<some_id>",
5
  $role: Role! = DEPLOYMENT_VIEWER
6
)
7
{
8
		deploymentAddUserRole(
9
			userId: $userId
10
			email: $email
11
			deploymentId: $deploymentId
12
			role: $role
13
		) {
14
			id
15
			user {
16
				username
17
			}
18
			role
19
			deployment {
20
				id
21
				releaseName
22
			}
23
		}
24
	}

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.

1
mutation removeUser {
2
	removeUser (
3
    id: "<user-id>"
4
  ) {
5
    uuid
6
    emails {address}
7
    status
8
  }
9
}

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.

1
mutation verifyEmail {
2
	verifyEmail (
3
    email: "<user-email>"
4
  )
5
}

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.

1
mutation workspaceAddUser(
2
    $workspaceUuid: Uuid = "<your-workspace-uuid>"
3
    $email: String! = "<user-email-address>"
4
    $role: Role! = WORKSPACE_VIEWER
5
    $bypassInvite: Boolean! = true
6
  ) {
7
    workspaceAddUser(
8
      workspaceUuid: $workspaceUuid
9
      email: $email
10
      role: $role
11
      bypassInvite: $bypassInvite
12
    ) {
13
      id
14
    }
15
  }

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.

1
mutation createSystemRoleBinding (
2
    $userId: ID! = "<user-id>"
3
    $role: Role! = SYSTEM_ADMIN
4
) {
5
  createSystemRoleBinding(
6
    userId: $userId
7
    role: $role
8
  ) {
9
    id
10
  }
11
}

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:

1
mutation UpdateDeploymentVariables {
2
  updateDeploymentVariables(
3
    deploymentUuid: ID! = "<deployment-id>",
4
  	releaseName: String! = "<deployment-release-name>",
5
    environmentVariables: [
6
      {key: "<environment-variable-1>",
7
      value: "<environment-variable-value-1>",
8
      isSecret: <true-or-false>},
9
      {key: "<environment-variable-2>",
10
      value: "<environment-variable-value-2>",
11
      isSecret: <true-or-false>}
12
    ]
13
  ) {
14
    key
15
    value
16
    isSecret
17
  }
18
}