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

# Sync prompts from a spreadsheet with n8n

> Keep a workspace's prompts in step with a spreadsheet using the generic n8n HTTP Request node, with idempotency keys, If-Match versions and safe replays.

Treat a spreadsheet as the source of truth for a workspace's prompts and apply the differences through the REST API. This guide uses the generic HTTP Request node of n8n, so it needs no community node. The same logic works in any automation tool that can send HTTP requests.

## 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 sheet with one row per prompt: a stable `rowId`, the `text`, and optionally a topic and a frequency.
* In n8n, a **Header Auth** credential with the name `Authorization` and the value `Bearer <your token>`. Never put the token in a node parameter or a workflow export.
* n8n interface labels change between versions. The stable inputs are the URL, the headers and the body of each request. See the [n8n HTTP Request node documentation](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/).

All values are synthetic.

## Workflow outline

| Node | Purpose |
| - | - |
| Schedule or Manual trigger | Starts a sync |
| Spreadsheet node | Reads the rows |
| HTTP Request: list prompts | `GET /brands/{brandId}/prompts?view=configuration`, paginated, to read each prompt's `id`, `text`, `status`, `frequency` and `version` |
| Code | Compares rows with existing prompts and outputs one item per change |
| Loop Over Items | Sends one change at a time, with a Wait node to stay under the rate limit |
| HTTP Request: write | `POST` to create, `PATCH` to update |

## Read the current state

Request the configuration view so archived prompts and versions are included:

```text theme={null}
GET https://www.qwairy.co/api/v1/brands/{{ $json.brandId }}/prompts?view=configuration&limit=100&offset=0
Authorization: Bearer <credential>
```

Page with `offset` until `pagination` reports no more results. The configuration view returns `id`, `text`, `status`, `frequency`, `monitoringEnabled`, `keywordId`, `tagIds` and `version` for each prompt. See [List prompts](https://docs.qwairy.co/developers/endpoints/prompts/list.md).

## Compute the changes

This Code node (JavaScript) matches rows to prompts by normalized text and emits a create or an update. The hash is only used to build a deterministic idempotency key.

```javascript theme={null}
const rows = $('Read sheet').all().map((i) => i.json);
const existing = $('List prompts').all().flatMap((i) => i.json.prompts);

const norm = (t) => t.trim().replace(/\s+/g, ' ').toLowerCase();
const hash = (s) => {
  let h = 5381;
  for (const c of s) h = ((h << 5) + h + c.charCodeAt(0)) >>> 0;
  return h.toString(36);
};
const byText = new Map(existing.map((p) => [norm(p.text), p]));

const out = [];
for (const row of rows) {
  const found = byText.get(norm(row.text));
  const frequency = row.frequency || null;
  if (!found) {
    out.push({ json: {
      op: 'create',
      key: 'prompt-sync-' + row.rowId + '-' + hash(norm(row.text) + '|' + frequency),
      body: { text: row.text.trim(), frequency },
    } });
  } else if (found.status === 'ARCHIVED') {
    out.push({ json: { op: 'restore', promptId: found.id, version: found.version } });
  } else if ((found.frequency ?? null) !== frequency) {
    out.push({ json: { op: 'update', promptId: found.id, version: found.version, body: { frequency } } });
  }
}
return out;
```

## Write the changes

**Create** with a deterministic key:

```text theme={null}
POST https://www.qwairy.co/api/v1/brands/{{ $json.brandId }}/prompts
Idempotency-Key: {{ $json.key }}
Content-Type: application/json

{{ JSON.stringify($json.body) }}
```

**Update or restore** with the version you just read, quoted:

```text theme={null}
PATCH https://www.qwairy.co/api/v1/brands/{{ $json.brandId }}/prompts/{{ $json.promptId }}
If-Match: "{{ $json.version }}"
Content-Type: application/json

{{ JSON.stringify($json.body ?? { status: 'ACTIVE' }) }}
```

For many identical changes, such as archiving or changing the frequency of up to 20 prompts, [bulk update prompts](https://docs.qwairy.co/developers/endpoints/prompts/bulk.md) is one request. It uses an `Idempotency-Key` and no `If-Match`, and returns an outcome for each prompt that you must inspect.

## Make replays safe

* **Idempotency.** The same key with the same body returns the original response for 24 hours, with `Idempotent-Replay: true`. The same key with a different body returns `409` `IDEMPOTENCY_CONFLICT`, which is why the key above includes a hash of the content. A `409` `IDEMPOTENCY_IN_PROGRESS` means the outcome is unknown: read the prompts again before you continue.
* **If-Match.** A `412` `PRECONDITION_FAILED` means someone changed the prompt after your read. Do not retry with the old version. Run the sync again so it reads fresh versions. A `428` means the header is missing.
* **Duplicates.** After 24 hours a replayed create is no longer recognized and returns `409` `CONFLICT` for a duplicate text. Reading first, as this workflow does, turns that case into a no-op, and restores an archived prompt instead of recreating it.
* **Rate limit.** Writes are limited to 120 per minute per team. Send one change per iteration and add a Wait node. On `429`, wait for `Retry-After` seconds before retrying, and use the same key for a create. On `503` `SERVICE_UNAVAILABLE` nothing changed: retry with bounded backoff.
* **Errors.** Set the write node to continue on error and route failures to a log, so one bad row does not stop the batch.

## Verify

Run the workflow twice. The second run should emit no changes. Then list prompts with `view=configuration` and compare the rows with the result.

## Limits

* The sync never deletes prompts: removed rows are not archived unless you add that rule. Archiving keeps answers and history.
* New monitored prompts add recurring credit use. Check [Credits](https://docs.qwairy.co/developers/endpoints/credits.md) before a large import.

## Related

* [Create a prompt](https://docs.qwairy.co/developers/endpoints/prompts/manage.md)
* [Update a prompt](https://docs.qwairy.co/developers/endpoints/prompts/update.md)
* [Rate limits](https://docs.qwairy.co/developers/rate-limits.md)


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