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

# Update a workspace

> Change a workspace's name, URL, countries, competitor detection and domain scope, and move it through its lifecycle using the current ETag in If-Match.

Updates properties and drives the workspace lifecycle. Send only the fields you
want to change.

> [!NOTE]
>
> Requires `If-Match`. See [Writing data](https://docs.qwairy.co/developers/writing-data.md) for the
> read-then-write pattern.

## Lifecycle

| From | To | Allowed |
| - | - | - |
| `DRAFT` | `LIVE` | Yes, activates the workspace |
| `DRAFT` | `ARCHIVED` | Yes |
| `LIVE` | `ARCHIVED` | Yes, once generation is idle |
| `ARCHIVED` | `LIVE` | Yes, restores it |
| `LIVE` or `ARCHIVED` | `DRAFT` | No, returns `409` |

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

Activating a workspace never starts generation on its own. Start work
explicitly with [Estimate and start runs](https://docs.qwairy.co/developers/endpoints/runs/manage.md).

After you change the name or move the workspace to `LIVE`, Qwairy evaluates
again the `Branded` or `Non-branded` system tag of the prompts that carry one.

**Authorization** `string` *required*

Bearer token. Example: `Bearer qw-api-xxx`

**If-Match** `string` *required*

The `ETag` you last read for this workspace.

**name** `string`

Display name

**description** `string`

Description, or `null` to clear it

**languageCode** `string`

Two-letter language code

**countryCode** `string`

ISO 3166-1 alpha-2 country code, for example `US`. It becomes the default
country, first in the workspace country catalog.

**status** `string`

Target status: `DRAFT`, `LIVE` or `ARCHIVED`

**url** `string | null`

Workspace URL, at most 2048 characters, or `null` to clear it. The domain
of the workspace cannot be changed.

**countryCodes** `string[]`

Complete replacement list of 1 to 50 uppercase two-letter country codes: the
workspace country catalog. The default country stays first. Removing a country
also removes it from the prompts that selected it; their past answers stay
available.

**autoDetectCompetitors** `boolean`

Whether Qwairy detects competitors automatically in answers. Disabling it
stops new automatic additions; existing competitors are still tracked.

**selfHostScope** `string`

Scope of the workspace pages and sources: `REGISTRABLE` for the registrable
domain and its relevant subdomains, or `EXACT_HOST` for the exact host and its
sub-subdomains only. A read can return `AUTO`, but a write does not accept it.

## Response

Returns `200`, the new `ETag` and a `workspace` object with the fields of
[Create a workspace](https://docs.qwairy.co/developers/endpoints/brands/create.md#response), including
`url`, `countryCodes`, `autoDetectCompetitors` and `selfHostScope`.

## Synthetic request

```bash theme={null}
curl -X PATCH "https://www.qwairy.co/api/v1/brands/$BRAND_ID" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H 'If-Match: "0"' \
  -H "Content-Type: application/json" \
  -d '{"status": "LIVE"}'
```

## Errors

| Status | Code | Cause |
| - | - | - |
| `400` | `INVALID_REQUEST` | Invalid field, for example a country code that is not ISO 3166-1 alpha-2 |
| `403` | `INSUFFICIENT_PLAN` | Archiving requires an agency, or a team over its workspace limit |
| `409` | `CONFLICT` | Restoring would duplicate an active workspace for the same domain and market |
| `409` | `INVALID_STATE_TRANSITION` | The transition is not allowed |
| `409` | `RESOURCE_BUSY` | Answers are still being generated; retry later |
| `409` | `QUOTA_EXCEEDED` | Activating would exceed your workspace limit |
| `412` | `PRECONDITION_FAILED` | The workspace changed since your read |
| `428` | `PRECONDITION_REQUIRED` | `If-Match` was missing |


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