> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the Houston API on Astro Private Cloud

The Houston API allows you to build applications that provision and manage resources on Astro Private Cloud. You can use the Houston API to 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 Astro Private Cloud UI, you can do programmatically with the Houston API.

To access the interactive API documentation for your Astro Private Cloud installation, go to `https://houston.<your-base-domain>/v1`.

## Schema overview

The Houston API uses the [GraphQL API](https://graphql.org/learn/) query language. You can make GraphQL requests using standard REST API tools such as [HTTP](https://www.apollographql.com/blog/making-graphql-requests-using-http-methods) and curl. GraphQL APIs support two main request types: *queries* and *mutations*. You can run these requests against *objects* which are similar to endpoints in REST APIs.

A *query* is a request for specific information and is similar to a `GET` request in a REST API. The primary difference between GraphQL queries and REST API queries is that GraphQL queries only return the fields that you specify within your request. For example, consider the following query to retrieve information about a user:

```graphql wrap theme={null}
query User {
  users(user: { email: "name@mycompany.com"} )
  {
    id
    roleBindings {role}
  }
}
```

The Houston API would only return the ID and role bindings for the user because those are the only fields specified in the query.

A *mutation* is a request to update data for a specific object. Different mutations exist for creating, updating, and deleting objects. When you write a mutation request, it's best practice to use [variables](https://graphql.org/learn/queries/#variables) to store the data you want to update. For example, consider the following example mutation:

```graphql wrap theme={null}
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
    bypassInvite: $bypassInvite
  ) {
    id
  }
}
```

In this mutation, the values to update are formatted as variables in the first part of the request, then applied in the second half. Variables marked with a `!` are required in order for the query to complete. Lastly, the mutation requests the Houston API to return `id` of the added user to confirm that the mutation was successful. In this way, it's possible to make a mutation and a query in a single request.

For more basic GraphQL usage rules and examples, see the [GraphQL documentation](https://graphql.org/learn/queries/).