# Bulk operations

URL: https://kywi-docs-production.up.railway.app/integrating/bulk-operations
Type: docPage

Bulk create and update cap at 100 items and refuse any payload carrying a `layout`, and one failing id rejects the whole batch for every route that takes ids.

Five routes hang off one content type, and they split into two families with different payloads and different limits. Create and update take `{ "items": [...] }` and are capped at 100 per request; delete, publish and unpublish take `{ "ids": [...] }` and are **not** capped at all.

## The five routes

Create up to 100. Needs the `write` action (author and up). The only one of the five that reads `?siteId=` — it has no ids to derive a site from.

Update up to 100. Each item must carry a non-empty string `id`; everything else on the item is the patch. No `?siteId=` on this route — with a target row per item, the site is derived from those rows and checked against your membership, not taken from the query string.

Soft-delete by id. Needs the `delete` action, which means the **siteAdmin** role — a key scoped only `read, write, publish` cannot reach it. No `?siteId=` here either, for the same reason as bulk update: the target rows supply their own site.

Publish by id, with `/bulk/unpublish` as its counterpart. Both need the `publish` action (editor and up) and both check the status ladder for every id before touching anything.

## One bad id refuses the whole batch

There is no partial-success envelope. Before any row is touched, every id is put through two independent gates — the per-document access list, and per-site membership — and either one failing returns a single 403 for the request. The second gate is the one that surprises people: a siteAdmin bypasses the document ACL but *not* the site check, so a siteAdmin of one site cannot reach another site's rows by id even though every other gate would let them.

Status transitions and field-level write permissions are checked across the batch too, each item against its own current status. Bulk is not a corridor around the single-node rules — see [Writing content from outside](/integrating/writing-content-from-outside/) for what those rules are.

## A layout key is refused by name

Bulk items are typed as opaque objects, so a `layout` in one would reach the database with none of the validation or admin-only-module gating the layout routes apply. Rather than weaken the gate, the field simply is not writable here — and the refusal names the offending index so you can find it in a hundred-item payload.

## PUT /api/v1/content/page/bulk — second item carried a "layout"

## What "bulk" does and does not guarantee

Delete, publish and unpublish are each a single statement over the id list, so they land together. **Create and update are loops** with no transaction around them: `createContent` or `updateContent` runs once per item, and a failure partway through leaves the earlier rows written. Treat those two as a convenience over a client-side loop, not as an atomic import.

Update also skips silently. An id that matches no row is not an error — it is simply absent from the result, so `updated` can be lower than the number of items you sent. The `ids` array is the list that actually landed; compare it against what you sent rather than trusting the count.

## PUT /api/v1/content/page/bulk — request

## 200 — one of the two landed

## Bulk delete fires no hooks

Bulk publish and unpublish dispatch a hook per row after the batch commits, which is what invalidates the content, feed, nav and AX caches and fires webhooks. The bulk DELETE route dispatches nothing — no `beforeDelete`, no `afterDelete` — unlike the single-node delete. Caches keep serving the deleted rows and no webhook is sent. If subscribers matter to you, delete one at a time. See [Webhooks](/integrating/webhooks/) and [Caching semantics for an integrator](/integrating/caching-semantics-for-an-integrator/).

## Only items is capped, and only ids is unchecked

Sending 101 `items` is a clean 400 (`{"path":"items","message":"Maximum 100 items per request"}`). Sending 101 `ids` is not refused at all — that array has a floor of one and no ceiling. Nor is an id checked for shape: a value that is not a UUID reaches Postgres and comes back as a 500, not a validation error. Batch and validate ids on your side.
