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

# Writing data

> Create and update Qwairy resources from your own systems: enable write access per token, retry safely with idempotency keys, and avoid lost updates.

API v1 commands let you manage workspaces, prompts, topics, tags, monitoring,
runs, actions, site diagnostics, prompt suggestions, webhook
endpoints, and the core Pitch Audit lifecycle from your own systems. The
reference contains **28 commands**: 27 create or change resources, and one
estimates a run without starting it or reserving credits.

Read access starts with Growth or Agency Growth. Commands require an active
**Business**, **Agency Business**, or **Enterprise** plan and write access
enabled on the API token. Pitch Audit commands also require an agency team. See
the full
[endpoint inventory](https://docs.qwairy.co/developers/endpoints/index.md).

## Enable write access on a token

Write access is enabled token by token. It is **off by default** on every
token, including the tokens you created before commands were available. You do
not need to rotate a token: keep using it and enable writes on it.

A team **Owner** or **Manager** enables write access in the token settings of
[Team Management > REST API](https://www.qwairy.co/dashboard/team/api). Until
then, every command made with that token returns `403` `API_KEY_READ_ONLY`
and reads keep working. See [API tokens](https://docs.qwairy.co/developers/api-keys.md#enable-write-access).

> [!WARNING]
>
> A valid key on Growth or Agency Growth receives `403` `INSUFFICIENT_PLAN` for
> commands. Inactive teams or subscriptions without API access fail
> authentication first with `401`.

Tokens are team-scoped and carry no user role. Enable writes only on the tokens
that need them, and review [Authentication](https://docs.qwairy.co/developers/authentication.md) before
sharing a token with an integration.

## Choose a command

| Resource | Commands |
| - | - |
| Workspaces | [Create](https://docs.qwairy.co/developers/endpoints/brands/create.md), [update](https://docs.qwairy.co/developers/endpoints/brands/update.md), [update monitoring](https://docs.qwairy.co/developers/endpoints/brands/update-monitoring.md) |
| Topics | [Create](https://docs.qwairy.co/developers/endpoints/keywords/manage.md), [update](https://docs.qwairy.co/developers/endpoints/keywords/update.md), [delete](https://docs.qwairy.co/developers/endpoints/keywords/delete.md) |
| Tags | [Create](https://docs.qwairy.co/developers/endpoints/tags/create.md), [update](https://docs.qwairy.co/developers/endpoints/tags/update.md), [delete](https://docs.qwairy.co/developers/endpoints/tags/delete.md) |
| Prompts | [Create](https://docs.qwairy.co/developers/endpoints/prompts/manage.md), [update or archive](https://docs.qwairy.co/developers/endpoints/prompts/update.md), [bulk update](https://docs.qwairy.co/developers/endpoints/prompts/bulk.md) |
| Runs | [Estimate](https://docs.qwairy.co/developers/endpoints/runs/estimate.md), [start](https://docs.qwairy.co/developers/endpoints/runs/manage.md) |
| Pitch Audits | [Create](https://docs.qwairy.co/developers/endpoints/pitch-audits/create.md), [save reviewed prompts](https://docs.qwairy.co/developers/endpoints/pitch-audits/save-prompts.md), [confirm](https://docs.qwairy.co/developers/endpoints/pitch-audits/confirm.md) |
| Actions | [Update a status](https://docs.qwairy.co/developers/endpoints/actions/update-status.md) |
| Site diagnostics | [Add pages](https://docs.qwairy.co/developers/endpoints/site-diagnostics/add-pages.md), [start an audit](https://docs.qwairy.co/developers/endpoints/site-diagnostics/start-audit.md) |
| Prompt suggestions | [Generate](https://docs.qwairy.co/developers/endpoints/prompt-suggestions/generate.md), [accept](https://docs.qwairy.co/developers/endpoints/prompt-suggestions/accept.md) |
| Webhook endpoints | [Create](https://docs.qwairy.co/developers/endpoints/webhooks/create.md), [update](https://docs.qwairy.co/developers/endpoints/webhooks/update.md), [delete](https://docs.qwairy.co/developers/endpoints/webhooks/delete.md), [rotate the secret](https://docs.qwairy.co/developers/endpoints/webhooks/rotate-secret.md), [test](https://docs.qwairy.co/developers/endpoints/webhooks/test.md), [redeliver](https://docs.qwairy.co/developers/endpoints/webhooks/redeliver.md) |

## Retry safely

Every mutating `POST` requires an `Idempotency-Key` header: a unique value you
choose for each logical operation, with at most 255 characters. The
non-mutating `POST /brands/{brandId}/runs/estimate` is the exception: it does
not require `Idempotency-Key`, but still uses command authorization and rate
limits.

This synthetic example creates a draft workspace:

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

The replay window is **24 hours**, scoped to the same API key and command:

* The same `Idempotency-Key` with the same path parameters and parsed body
  replays a completed response, including its status, `Location`, and `ETag`.
  The response includes `Idempotent-Replay: true`.
* The same key with different path parameters or body returns `409`
  `IDEMPOTENCY_CONFLICT`.
* An in-progress request or an unresolved outcome returns `409`
  `IDEMPOTENCY_IN_PROGRESS`. Read the resource before starting a new logical
  operation.

Retry a timed-out request with the same API key, command, idempotency key, and
payload. A different API key or an expired replay window does not reuse the
stored response. Reconcile the current state before issuing a new key after
an uncertain outcome, especially for operations that reserve credits.

## Avoid lost updates

`PATCH` and `DELETE` commands require an `If-Match` header
carrying the `ETag` you last read. Mutable workspace resources expose a
`version`; Pitch Audits expose a `revision`. Both return the corresponding
`ETag` on read. Treat these values as opaque concurrency tokens: copy the
returned `ETag` unchanged, and do not calculate the next version or assume
versions increase by one.

```bash theme={null}
# 1. Read the current state
curl -i "https://www.qwairy.co/api/v1/brands/$BRAND_ID" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
# ETag: "4"

# 2. Write against that exact version
curl -X PATCH "https://www.qwairy.co/api/v1/brands/$BRAND_ID" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
  -H 'If-Match: "4"' \
  -H "Content-Type: application/json" \
  -d '{"status": "LIVE"}'
```

| Situation | Response |
| - | - |
| `If-Match` missing | `428` `PRECONDITION_REQUIRED` |
| Resource changed since your read | `412` `PRECONDITION_FAILED` |

On `412`, re-read the resource and reconcile your change with the latest
state. `If-Match: *` accepts any current version and removes protection against
overwriting a concurrent change. A retry with an old version can return `412`
even if your first request succeeded; read the resource to determine its state.

Use `?view=configuration` on prompt, topic and tag lists to retrieve mutable
fields and versions, including archived prompts and labels with no analytics.
Use the prompt configuration detail, [topic detail](https://docs.qwairy.co/developers/endpoints/keywords/get.md),
or [tag detail](https://docs.qwairy.co/developers/endpoints/tags/get.md) to read the resource and its
`ETag`. Monitoring has its own detail read and ETag.

## Preserve configuration values

For `PATCH`, an omitted field keeps its current value. Send `null` only when
the endpoint schema allows it. For example, `description: null` clears a
workspace description and `keywordId: null` detaches a prompt from its topic.
Prompt `frequency: null` clears the stored frequency override; it is distinct
from the explicit value `"NONE"`. `tagIds: []` removes all prompt tags except the `Branded` or `Non-branded` system tag, which Qwairy sets from the prompt text in a workspace created from v1.21.

Do not convert `null` to an empty string, zero, or an empty array. Read and
write the configuration representation, including archived prompts and labels
with no analytics, when synchronizing settings.

## Interpret command responses

| Status | Meaning |
| - | - |
| `200` | The command completed, or a run estimate was returned |
| `201` | A workspace, prompt, topic, tag, or webhook endpoint was created |
| `202` | A run, Pitch Audit, page audit, prompt suggestion generation, or webhook delivery was accepted for asynchronous processing |
| `204` | A webhook endpoint was deleted |

For `201` and `202`, follow `Location` with `GET` to read current state. A
`202` is not proof that provider answer collection has finished. Use
[run detail](https://docs.qwairy.co/developers/endpoints/runs/get.md) or Pitch Audit detail for the
fields exposed by that workflow.

Bulk prompt commands return `200` with an individual result for each prompt:
`updated`, `unchanged`, or `not_found`. Inspect every item; the HTTP status
alone does not mean every requested prompt was changed. A bulk request accepts
at most 20 prompts and uses idempotency, without an `If-Match` requirement.

[Accepting prompt suggestions](https://docs.qwairy.co/developers/endpoints/prompt-suggestions/accept.md)
also returns `200` with an outcome for each item. Inspect every item there too.

## Preview with dryRun

These commands accept `dryRun: true`, which validates the request and returns
the result without changing anything:

* [Bulk update prompts](https://docs.qwairy.co/developers/endpoints/prompts/bulk.md)
* [Update monitoring](https://docs.qwairy.co/developers/endpoints/brands/update-monitoring.md)
* [Start a page audit](https://docs.qwairy.co/developers/endpoints/site-diagnostics/start-audit.md),
  which returns a `PREVIEW` audit with the `creditsReserved` it would reserve
* [Accept prompt suggestions](https://docs.qwairy.co/developers/endpoints/prompt-suggestions/accept.md),
  which also reports the recurring credit consumption in `dailyCredits`

## Get notified when work finishes

A `202` response means the work was accepted. Poll the resource named by
`Location`, or subscribe an
[integration webhook](https://docs.qwairy.co/developers/integration-webhooks/overview.md) to the matching
completion event. Integration webhooks are available on Business, Agency
Business and Enterprise plans.

## Automate a Pitch Audit

An agency team on a write-enabled plan can run the reviewable Pitch Audit
workflow through three commands:

1. [Create a Pitch Audit](https://docs.qwairy.co/developers/endpoints/pitch-audits/create.md) with an
   `Idempotency-Key`.
2. Read it with [Get Pitch Audit](https://docs.qwairy.co/developers/endpoints/pitch-audits/get.md), then
   [save the reviewed prompts](https://docs.qwairy.co/developers/endpoints/pitch-audits/save-prompts.md)
   against the returned `ETag` when prompt review is ready.
3. [Confirm the Pitch Audit](https://docs.qwairy.co/developers/endpoints/pitch-audits/confirm.md) with a
   new `Idempotency-Key` to queue billable answer collection.

Set `autoStartResponses=true` during creation only when you deliberately want
to skip manual prompt review. Pitch Audit retries and server-generated exports
remain dashboard operations. MCP clients can run the same lifecycle with
separate write scopes, previews and confirmation tokens; see
[MCP write access](https://docs.qwairy.co/mcp/write/overview.md).

## Error format

Every command error, including authentication `401` and rate-limit `429`,
carries a stable code and a request identifier:

```json theme={null}
{
  "error": {
    "code": "INVALID_STATE_TRANSITION",
    "message": "A workspace cannot move from LIVE to DRAFT.",
    "requestId": "4f1d0b1e-6c1a-4a2f-9a17-2f2b9a3c4d5e"
  }
}
```

Match on `error.code` and preserve `error.requestId` when contacting support.
Command responses also include `X-Request-Id`. The read authentication and
rate-limit envelopes differ; see [Error codes](https://docs.qwairy.co/developers/errors.md) for a client
that handles both shapes.

| Code | Meaning |
| - | - |
| `INSUFFICIENT_PLAN` | The plan does not include write access |
| `API_KEY_READ_ONLY` | Writes are not enabled on this API token |
| `IDEMPOTENCY_CONFLICT` | Key reused with a different body |
| `IDEMPOTENCY_IN_PROGRESS` | The outcome is uncertain; reconcile before new work |
| `INVALID_STATE_TRANSITION` | The requested lifecycle change is not allowed |
| `RESOURCE_BUSY` | Work is in progress; read its state before retrying |
| `QUOTA_EXCEEDED` | A plan limit is reached |
| `INSUFFICIENT_CREDITS` | Not enough credits for this operation |
| `SERVICE_UNAVAILABLE` | The write limiter is unavailable; retry shortly |

A `503 SERVICE_UNAVAILABLE` also covers suspended writes. In both cases the
command did not run.

A resource belonging to another team is treated as not found. Single-resource
commands return `404`; bulk prompt commands can report `not_found` per item.
Other `409` conflicts, `412` stale versions, and `428` missing preconditions
need reconciliation or a corrected request before retrying.

## Rate limits

Commands have their own budget, separate from reads: **120 requests per
minute** and **5,000 per day** per team. This includes run estimates and
idempotent replays. Command traffic does not consume the read request budget.

Honor `Retry-After` on `429`. If the write limiter is unavailable or writes are
suspended, the request returns `503` `SERVICE_UNAVAILABLE` before the command
executes and nothing changes. Use bounded
backoff and the same idempotency key when retrying a mutating `POST`. See
[Rate limits](https://docs.qwairy.co/developers/rate-limits.md).

## Scope and lifecycle limits

* Creating a workspace never starts an analysis or a billable run. It creates a
  `DRAFT`; you activate it when you are ready.
* Archiving a prompt keeps its answers and history, and can be undone.
* Deleting a topic or a tag removes the label only. Prompts are detached, never
  deleted. The `Branded` and `Non-branded` system tags cannot be created, renamed,
  updated or deleted; these requests return `400 INVALID_REQUEST`.
* Credits can be inspected with `GET /api/v1/credits`, but allocation,
  transfers and purchases remain dashboard actions.
* Runs can be estimated, started, listed, and read. Public API v1 does not
  provide run cancellation or retry commands.
* Creating a Pitch Audit prepares its prompts. Confirming it, or enabling
  automatic answer collection during creation, starts the billable answer
  workflow.

> [!NOTE]
>
> Team membership, roles, invitations and Viewer workspace access are not part
> of the API. Manage them in the dashboard.


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