# 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/) 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/) - Search and filter workspaces with pagination

See the [MCP Tools](/mcp/tools/) 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/))
* Each building contains **unit types** and **units** (see [Structure & Terms](/concepts/structure-and-terms/))
* **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/) for more information on how the inventory hierarchy works within a workspace.