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

# Create a workspace

> Create a workspace in DRAFT status. Nothing else happens: no domain analysis, no description generation and no billable run until you activate it.

Creates a workspace in `DRAFT`. Nothing else happens: no domain analysis, no
description generation and no billable run. Configure it, then activate it with
[Update a workspace](https://docs.qwairy.co/developers/endpoints/brands/update.md).

> [!NOTE]
>
> Requires any active API key on a Business, Agency Business or Enterprise
> plan. Existing keys work without rotation. See
> [Writing data](https://docs.qwairy.co/developers/writing-data.md).

**Authorization** `string` *required*

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

**Idempotency-Key** `string` *required*

Unique key for this creation. Replaying it returns the original workspace
instead of creating a duplicate.

**name** `string` *required*

Display name, up to 120 characters.

**domain** `string` *required*

Valid public hostname, up to 253 characters, without scheme, port or path.
Example: `acme.com`.

**description** `string`

Optional description. Left empty if omitted; nothing is generated for you.

**languageCode** `string`

Two-letter language code. Defaults to `FR`.

**countryCode** `string`

ISO 3166-1 alpha-2 country code. Defaults to `FR`. Any other value returns
`400 INVALID_REQUEST`.

## Response

Returns `201` with a `Location` header and the workspace `ETag`.

**workspace.id** `string`

Opaque workspace identifier

**workspace.status** `string`

Always `DRAFT` for a newly created workspace

**workspace.version** `number`

Current version, used as the `If-Match` value for later updates

**workspace.url** `string | null`

Workspace URL, or `null` when none is set

**workspace.countryCodes** `string[]`

Workspace country catalog. The default country comes first

**workspace.autoDetectCompetitors** `boolean`

Whether Qwairy detects competitors automatically in answers

**workspace.selfHostScope** `string`

`REGISTRABLE`, `EXACT_HOST` or `AUTO`. A read can return `AUTO`; a write cannot set it

The response also returns `name`, `domain`, `description`, `languageCode`,
`countryCode`, `lifecycleVersion`, `createdAt` and `updatedAt`.

## Synthetic request

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/brands" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: create-acme-001" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme", "domain": "acme.com", "countryCode": "US"}'
```

## Synthetic response

```json theme={null}
{
  "workspace": {
    "id": "b1c2d3e4-0000-4000-8000-000000000000",
    "name": "Acme",
    "domain": "acme.com",
    "description": null,
    "languageCode": "FR",
    "countryCode": "US",
    "status": "DRAFT",
    "version": 0,
    "lifecycleVersion": 0,
    "createdAt": "2026-03-01T09:00:00.000Z",
    "updatedAt": "2026-03-01T09:00:00.000Z",
    "url": null,
    "countryCodes": ["US"],
    "autoDetectCompetitors": true,
    "selfHostScope": "REGISTRABLE"
  }
}
```

## Errors

| Status | Code | Cause |
| - | - | - |
| `403` | `INSUFFICIENT_PLAN` | The team plan does not include write access |
| `409` | `CONFLICT` | A workspace already exists for this domain |
| `409` | `IDEMPOTENCY_CONFLICT` | Key reused with a different body |


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