> ## 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.

# Manage Workspaces with the APC API

<Note>
  The examples on this page show common ways to use the APC API — they're not a complete API reference. For the full, interactive API documentation for your installation, including every available query, mutation, and type, go to `https://houston.<your-base-domain>/v1`, and click on the **Docs** tab. See [Develop and test APC API queries](/docs/astro-private-cloud/v-2-x/houston-api-develop-test) for more on using the built-in GraphQL explorer.
</Note>

You can use the APC API to create, update, and delete Workspaces programmatically. These mutations require System Admin permissions, or Workspace Admin permissions on the target Workspace when updating or deleting it.

## Create a Workspace

Use the `createWorkspace` mutation to create a Workspace. The `label` is required, and `description` is optional. The mutation returns details about the new Workspace, including its `id`.

```graphql wrap theme={null}
mutation CreateWorkspace(
  $label: String! = "<workspace-label>"
  $description: String = "<workspace-description>"
) {
  createWorkspace(
    label: $label
    description: $description
  ) {
    id
    label
    description
    createdAt
    updatedAt
  }
}
```

## Update a Workspace

Use the `updateWorkspace` mutation to update an existing Workspace. Provide the `workspaceUuid` and a `payload` that contains the fields to update, such as `label` and `description`. To retrieve the `workspaceUuid`, run `astro workspace list` or use the [`workspaces`](/docs/astro-private-cloud/v-2-x/houston-api-example-queries#workspaces) query.

```graphql wrap theme={null}
mutation UpdateWorkspace(
  $workspaceUuid: Uuid! = "<workspace-id>"
  $payload: JSON! = { label: "<new-label>", description: "<new-description>" }
) {
  updateWorkspace(
    workspaceUuid: $workspaceUuid
    payload: $payload
  ) {
    id
    label
    description
    createdAt
    updatedAt
  }
}
```

## Delete a Workspace

Use the `deleteWorkspace` mutation to delete a Workspace. Provide the `workspaceUuid` of the Workspace to delete. The mutation returns details about the deleted Workspace to confirm the operation.

```graphql wrap theme={null}
mutation DeleteWorkspace(
  $workspaceUuid: Uuid! = "<workspace-id>"
) {
  deleteWorkspace(
    workspaceUuid: $workspaceUuid
  ) {
    id
    label
    description
  }
}
```