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

# Onboard a client with the API

> Create a DRAFT workspace, configure topics, tags, prompts and monitoring, activate it, start a first run and wait for the run.completed webhook event.

Set up a new client workspace from your own system, from an empty workspace to a first run, using the REST API. The workspace stays in `DRAFT` while you configure it, so nothing is monitored or billed until you activate it and start a run.

## Before you start

* A Business, Agency Business or Enterprise plan, and an API token with write access enabled by an Owner or Manager. See [Writing data](https://docs.qwairy.co/developers/writing-data.md).
* A public HTTPS endpoint if you want to receive the `run.completed` event. Otherwise, poll the run.
* Enough credits for the first run. Check with [Credits](https://docs.qwairy.co/developers/endpoints/credits.md).

All values below are synthetic. Every `POST` needs a unique `Idempotency-Key`, and every `PATCH` needs `If-Match` with the `ETag` you last read.

## Steps

**1. Create the workspace in DRAFT**

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

Keep `workspace.id` as `BRAND_ID`. The workspace is `DRAFT`, and the `ETag` header carries its version.

**2. Create topics and tags**

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/keywords" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: onboard-acme-topic-crm" \
  -H "Content-Type: application/json" \
  -d '{"text": "CRM software"}'

curl -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/tags" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: onboard-acme-tag-pricing" \
  -H "Content-Type: application/json" \
  -d '{"name": "Pricing", "color": "#7B3AEE"}'
```

Keep `topic.id` as `TOPIC_ID` and `tag.id` as `TAG_ID`. See [Create a topic](https://docs.qwairy.co/developers/endpoints/keywords/manage.md) and [Create a tag](https://docs.qwairy.co/developers/endpoints/tags/create.md).

**3. Create prompts**

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/prompts" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: onboard-acme-prompt-001" \
  -H "Content-Type: application/json" \
  -d '{"text": "Which CRM tools support small sales teams?", "frequency": "WEEKLY", "keywordId": "'"$TOPIC_ID"'", "tagIds": ["'"$TAG_ID"'"]}'
```

Create one prompt per request. Prompts under monitoring add recurring credit use. See [Create a prompt](https://docs.qwairy.co/developers/endpoints/prompts/manage.md).

**4. Set monitoring**

Read [Get monitoring](https://docs.qwairy.co/developers/endpoints/brands/monitoring.md) for the selected models and the `ETag`. Preview the change with `dryRun`, then save it. When no setting exists yet, the first `ETag` is `"0"`.

```bash theme={null}
curl -X PATCH "https://www.qwairy.co/api/v1/brands/$BRAND_ID/monitoring" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H 'If-Match: "0"' \
  -H "Content-Type: application/json" \
  -d '{"frequency": "WEEKLY", "analysisWeekDay": 2, "dryRun": true}'
```

Repeat the request without `dryRun` to save. See [Update monitoring](https://docs.qwairy.co/developers/endpoints/brands/update-monitoring.md).

**5. Subscribe to run.completed**

Create an [integration webhook](https://docs.qwairy.co/developers/integration-webhooks/overview.md) endpoint limited to the new workspace. Store the returned `secret`: it is shown once.

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/webhooks" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: onboard-acme-webhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/qwairy", "events": ["run.completed", "run.failed"], "brandIds": ["'"$BRAND_ID"'"]}'
```

Verify each delivery with [Verify signatures](https://docs.qwairy.co/developers/integration-webhooks/verify-signatures.md).

**6. Activate the workspace**

Read the workspace again to get its current `ETag`, then move it to `LIVE`. This example assumes the `ETag` you read is `"2"`.

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

Activation never starts generation. A workspace over the plan limit returns `409` `QUOTA_EXCEEDED`. See [Update a workspace](https://docs.qwairy.co/developers/endpoints/brands/update.md).

**7. Estimate, then start the first run**

```bash theme={null}
curl -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/runs/estimate" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Content-Type: application/json" -d '{}'

curl -i -X POST "https://www.qwairy.co/api/v1/brands/$BRAND_ID/runs" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H "Idempotency-Key: onboard-acme-first-run" \
  -H "Content-Type: application/json" -d '{}'
```

Check `sufficientCredits` in the estimate before you start. The start request returns `202` with a `Location` header and reserves the planned credits. See [Estimate a run](https://docs.qwairy.co/developers/endpoints/runs/estimate.md) and [Start a run](https://docs.qwairy.co/developers/endpoints/runs/manage.md).

**8. Wait for run.completed**

Your endpoint receives a signed `run.completed` event when the run reaches a final state:

```json theme={null}
{
  "id": "evt_7c1b0f9e-2d4a-4b8f-9e1a-5a6c7d8e9f01",
  "event": "run.completed",
  "createdAt": "2026-11-02T09:14:07Z",
  "teamId": "team_synthetic_01",
  "brandId": "brand_synthetic_01",
  "data": {
    "runId": "run_synthetic_01",
    "status": "COMPLETED",
    "counts": { "requested": 40, "completed": 40, "failed": 0, "skipped": 0, "cancelled": 0 }
  }
}
```

Deduplicate on `id`: delivery is at least once. A `COMPLETED_WITH_WARNINGS` status means some answers failed, so read `counts`. Without a webhook, poll [List runs](https://docs.qwairy.co/developers/endpoints/runs/list.md).

## Verify the result

* [Get monitoring](https://docs.qwairy.co/developers/endpoints/brands/monitoring.md) returns the saved schedule and models.
* [List prompts](https://docs.qwairy.co/developers/endpoints/prompts/list.md) with `view=configuration` returns the prompts, their topics and tags.
* [Credits](https://docs.qwairy.co/developers/endpoints/credits.md) shows what the run reserved.

## Limits and rollback

* Replaying a request with the same `Idempotency-Key` and body returns the original response for 24 hours. Use a new key for a new logical operation, and read the state first after an uncertain outcome.
* `412` means the resource changed since your read. Read it again and reapply your change.
* A `LIVE` workspace cannot return to `DRAFT`. Archive it with `status: ARCHIVED` if the client leaves.
* There is no run cancellation in API v1.

## Related

* [Writing data](https://docs.qwairy.co/developers/writing-data.md)
* [Integration webhook events](https://docs.qwairy.co/developers/integration-webhooks/events.md)
* [Run write tool](https://docs.qwairy.co/mcp/write/runs.md) for the MCP equivalent of the first run.


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