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

# Workspace and monitoring write tools

> Create a workspace, update its profile and lifecycle, and change monitoring frequency and models through MCP, with a confirmation before each change.

These tools create and configure workspaces. Read [MCP write access](https://docs.qwairy.co/mcp/write/overview.md) first for plans, scopes, roles, `dryRun`, `expectedVersion` and confirmation tokens. All examples use synthetic data.

| Tool | Scope | Minimum role | Confirmation | REST equivalent |
| - | - | - | - | - |
| `create_workspace` | `write:workspaces` | Manager | `always` | [`POST /brands`](https://docs.qwairy.co/developers/endpoints/brands/create) |
| `update_workspace` | `write:workspaces` | Manager | `always` | [`PATCH /brands/{brandId}`](https://docs.qwairy.co/developers/endpoints/brands/update) |
| `update_monitoring` | `write:monitoring` | Manager | `always` | [`PATCH /brands/{brandId}/monitoring`](https://docs.qwairy.co/developers/endpoints/brands/update-monitoring) |

## create\_workspace

Create a workspace in `DRAFT` status in a team. It uses a workspace slot of the plan. Nothing is generated or monitored until the workspace goes `LIVE`.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `teamId` | string | Yes | Team that owns the new workspace. It must be a team your token may use |
| `name` | string | Yes | Display name, up to 120 characters |
| `domain` | string | Yes | Bare hostname without scheme or path, up to 253 characters |
| `description` | string | No | Workspace description |
| `languageCode` | string | No | Two-letter language code |
| `countryCode` | string | No | Two-letter country code |
| `dryRun` | boolean | No | Preview without creating |
| `confirmationToken` | string | No | Token returned by the preview |

### Example

```text theme={null}
You: Create a workspace for Acme Analytics, acme.example, in my agency team.

Assistant: calls create_workspace with
  {"teamId": "team_01", "name": "Acme Analytics", "domain": "acme.example", "countryCode": "US"}

Qwairy: returns a preview. The workspace is created as DRAFT and uses one
workspace slot. It returns a confirmationToken.

You: Go ahead.

Assistant: calls create_workspace again with the same arguments and the token.
The workspace is created in DRAFT status. Nothing is monitored yet.
```

***

## update\_workspace

Change the profile of a workspace, or move it between `DRAFT`, `LIVE` and `ARCHIVED`. Send only the fields you want to change.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `brandId` | string | Yes | Workspace ID from `list_brands` |
| `expectedVersion` | integer | Yes | Workspace `version` you last read |
| `name` | string | No | Display name |
| `description` | string | No | Description |
| `languageCode` | string | No | Two-letter language code |
| `countryCode` | string | No | Two-letter country code |
| `status` | string | No | `DRAFT`, `LIVE` or `ARCHIVED` |
| `url` | string | No | Workspace URL, up to 2048 characters |
| `countryCodes` | string\[] | No | Workspace country catalog, up to 50 codes. The default country stays first. Removing a country removes it from the prompts that selected it |
| `autoDetectCompetitors` | boolean | No | Whether Qwairy detects competitors automatically in answers |
| `selfHostScope` | string | No | `REGISTRABLE` counts every host of the registrable domain as the brand. `EXACT_HOST` counts only the configured host and its subdomains |
| `dryRun` | boolean | No | Preview without changing |
| `confirmationToken` | string | No | Token returned by the preview |

The domain, the workspace type and the confirmed onboarding profile cannot be changed.

### Lifecycle and confirmation

Every change needs a confirmation token from a preview. A move to `LIVE` also prices the collection it triggers.

| From | To | Allowed |
| - | - | - |
| `DRAFT` | `LIVE` | Yes |
| `DRAFT` | `ARCHIVED` | Yes |
| `LIVE` | `ARCHIVED` | Yes, once generation is idle |
| `ARCHIVED` | `LIVE` | Yes, restores it |
| `LIVE` or `ARCHIVED` | `DRAFT` | No |

As in the dashboard, archiving is available to agencies, or to any team while it has more active workspaces than its plan includes. Restoring is refused while another active workspace tracks the same domain for the same language and country.

Activating a workspace does not start a run, but the next scheduler pass collects the prompts that are due: those never collected while automatic answers are on, and those the schedule collects that day (for example on the analysis day of a weekly workspace). The preview prices that collection in `credits.oneOff`. To collect at once, use [`start_run`](https://docs.qwairy.co/mcp/write/runs).

### Example

```text theme={null}
You: Add Canada to the Acme Analytics countries.

Assistant: reads the workspace, then calls update_workspace with
  {"brandId": "brand_01", "expectedVersion": 3, "countryCodes": ["US", "CA"], "dryRun": true}

Qwairy: previews the change. Existing prompts keep their countries.

Assistant: once you approve the preview, repeats the call without dryRun and
with its confirmationToken.
```

***

## update\_monitoring

Change the monitoring frequency, schedule and models of a workspace, or stop its schedule with frequency `NONE`.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `brandId` | string | Yes | Workspace ID |
| `expectedVersion` | integer | Yes | Monitoring `version` you last read |
| `frequency` | string | No | `NONE`, `DAILY`, `WEEKLY` or `MONTHLY` |
| `analysisWeekDay` | integer | No | Day from 1 to 7 for weekly monitoring |
| `analysisMonthDay` | integer | No | Day from 1 to 28 for monthly monitoring |
| `autoGenerateAnswers` | boolean | No | Whether scheduled analysis generates answers automatically |
| `models` | string\[] | No | Replacement list of up to 20 model codes |
| `dryRun` | boolean | No | Preview without changing |
| `confirmationToken` | string | No | Token returned by the preview |

Every change needs a confirmation token from a preview, which reports any change in recurring credit use, for example a move from weekly to daily monitoring or a larger model list. `NONE` stops the prompts that inherit the workspace schedule; prompts with their own frequency keep running, as in the dashboard. It keeps the monitoring setting of each prompt, and work already accepted can still finish. A workspace without saved settings has no model and does not generate answers automatically.

### Example

```text theme={null}
You: Move Acme Analytics to daily monitoring.

Assistant: calls update_monitoring with
  {"brandId": "brand_01", "expectedVersion": 4, "frequency": "DAILY"}

Qwairy: returns a preview. The change increases recurring credit use. It
returns a confirmationToken and executes nothing.

You: That is expected. Confirm.

Assistant: calls update_monitoring again with the same arguments and the token.
```

## Related

* [Run and credit tools](https://docs.qwairy.co/mcp/tools/runs.md) to check the balance before raising frequency.
* [Writing data](https://docs.qwairy.co/developers/writing-data.md) for the REST equivalents.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.