Skip to main content
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.

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 returns 403 API_KEY_READ_ONLY and reads keep working. See API tokens.
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 before sharing a token with an integration.

Choose a command

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

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

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 accept dryRun: true, which validates the request and returns the result without changing anything:

Get notified when work finishes

A 202 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:
  1. Create a Pitch Audit with an Idempotency-Key.
  2. Read it with Get Pitch Audit, then save the reviewed prompts against the returned ETag when prompt review is ready.
  3. Confirm the Pitch Audit 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.

Error format

Every command error, including authentication 401 and rate-limit 429, carries a stable code and a request identifier:
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 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. 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.

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.
Team membership, roles, invitations and Viewer workspace access are not part of the API. Manage them in the dashboard.