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. Until then, every command made with that token returns403 API_KEY_READ_ONLY
and reads keep working. See API tokens.
Tokens are team-scoped and carry no user role. Enable writes only on the tokens
that need them, and review Authentication before
sharing a token with an integration.
Choose a command
Retry safely
Every mutatingPOST 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:
- The same
Idempotency-Keywith the same path parameters and parsed body replays a completed response, including its status,Location, andETag. The response includesIdempotent-Replay: true. - The same key with different path parameters or body returns
409IDEMPOTENCY_CONFLICT. - An in-progress request or an unresolved outcome returns
409IDEMPOTENCY_IN_PROGRESS. Read the resource before starting a new logical operation.
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.
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,
or tag detail to read the resource and its
ETag. Monitoring has its own detail read and ETag.
Preserve configuration values
ForPATCH, 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
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 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
also returns 200 with an outcome for each item. Inspect every item there too.
Preview with dryRun
These commands acceptdryRun: true, which validates the request and returns
the result without changing anything:
- Bulk update prompts
- Update monitoring
- Start a page audit,
which returns a
PREVIEWaudit with thecreditsReservedit would reserve - Accept prompt suggestions,
which also reports the recurring credit consumption in
dailyCredits
Get notified when work finishes
A202 response means the work was accepted. Poll the resource named by
Location, or subscribe an
integration webhook 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:- Create a Pitch Audit with an
Idempotency-Key. - Read it with Get Pitch Audit, then
save the reviewed prompts
against the returned
ETagwhen prompt review is ready. - Confirm the Pitch Audit with a
new
Idempotency-Keyto queue billable answer collection.
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.
Error format
Every command error, including authentication401 and rate-limit 429,
carries a stable code and a request identifier:
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 for a client
that handles both shapes.
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. HonorRetry-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.
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
BrandedandNon-brandedsystem tags cannot be created, renamed, updated or deleted; these requests return400 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.
Team membership, roles, invitations and Viewer workspace access are not part
of the API. Manage them in the dashboard.

