# Workspaces

A workspace is the top-level organisational unit in Lavanda. It serves as the central hub where users manage buildings, configure integrations, and carry out day-to-day operational tasks.

Most data in the Lavanda API is scoped to a workspace. When you authenticate with your API credentials, the token grants access to one or more workspaces depending on how your permissions are configured. See [Auth](/concepts/auth.md) for details.

## Key Concepts

### Multi-workspace setups

Many customers manage multiple workspaces. A common pattern is to dedicate one workspace per building, though the structure is flexible and depends on how the customer organises their portfolio.

### Status

A workspace has a status that indicates whether it is currently in use:

| Status    | Description                           |
| --------- | ------------------------------------- |
| `ACTIVE`  | The workspace is live and operational |
| `CHURNED` | The workspace is no longer active     |

### Demo workspaces

Workspaces can be flagged as demo workspaces. Demo workspaces are useful for testing and evaluation purposes without affecting production data.

## GraphQL API

### Types

#### `Workspace`

| Field               | Type               | Description                                     |
| ------------------- | ------------------ | ----------------------------------------------- |
| `id`                | `String!`          | Unique identifier                               |
| `name`              | `String!`          | The name of the workspace                       |
| `slug`              | `String!`          | A URL-friendly identifier for the workspace     |
| `status`            | `Status!`          | Whether the workspace is `ACTIVE` or `CHURNED`  |
| `demo`              | `Boolean!`         | Whether this is a demo workspace                |
| `logoUrl`           | `String`           | URL of the workspace logo                       |
| `externalBrandUuid` | `String`           | External brand identifier for the workspace     |
| `crmNamespace`      | `CrmNamespace`     | The CRM namespace associated with the workspace |
| `createdAt`         | `ISO8601DateTime`  | When the workspace was created                  |
| `updatedAt`         | `ISO8601DateTime!` | When the workspace was last updated             |

#### Enums

**`Status`** - The status of a workspace:

| Value     | Description                           |
| --------- | ------------------------------------- |
| `ACTIVE`  | The workspace is live and operational |
| `CHURNED` | The workspace is no longer active     |

### Querying Workspaces

#### Get a single workspace

```graphql
query Workspace($id: ID!) {
  awc {
    workspace(id: $id) {
      id
      name
      slug
      status
      demo
      logoUrl
      createdAt
      updatedAt
    }
  }
}
```

```json
{
  "id": "workspace-id"
}
```

#### List workspaces

The `workspaces` query returns a paginated connection. You can filter by name, slug, or status.

```graphql
query Workspaces($filters: WorkspacesFiltersInput, $first: Int, $after: String) {
  awc {
    workspaces(filters: $filters, first: $first, after: $after) {
      nodes {
        id
        name
        slug
        status
      }
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

```json
{
  "filters": {
    "status": {
      "eq": "ACTIVE"
    }
  },
  "first": 10
}
```

#### Available filters

| Filter   | Type                    | Description                                                      |
| -------- | ----------------------- | ---------------------------------------------------------------- |
| `name`   | `WorkspacesNameInput`   | Filter by workspace name. Supports `search` for partial matching |
| `slug`   | `WorkspacesSlugInput`   | Filter by exact slug match using `eq`                            |
| `status` | `WorkspacesStatusInput` | Filter by status using `eq` (e.g. `ACTIVE` or `CHURNED`)         |

## MCP Tools

If you are using the Lavanda MCP integration, the following tools are available for working with workspaces:

* [search\_workspaces](/mcp/tools/awc/search_workspaces.md) - Search and filter workspaces with pagination

See the [Tools](/mcp/tools.md) overview for setup instructions and the full list of available tools.

## Relationships

Workspaces sit at the top of the data hierarchy. Most entities in the API are scoped to a workspace:

* A workspace contains one or more **buildings** (see [Buildings](/spaces-and-inventory/buildings.md))
* Each building contains **unit types** and **units** (see [Structure & Terms](/concepts/structure-and-terms.md))
* **Bookings**, **leads**, **contacts**, **tickets**, **invoices**, and other domain entities are all associated with a workspace
* **Users** can belong to multiple workspaces, with roles and permissions configured per workspace

See [Structure & Terms](/concepts/structure-and-terms.md) for more information on how the inventory hierarchy works within a workspace.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lavanda.app/workspaces/workspaces.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.