Idempotency and safe writes

Networks fail in the middle of requests. These three mechanisms let you retry without creating duplicates or losing someone else's work.

Idempotency keys

Create operations that are expensive to repeat accept an Idempotency-Key header. The reference marks them, and the OpenAPI document sets x-kanorio-idempotent: true on them.

curl -X POST https://app.kanorio.com/api/v1/sites/ws_example123/collections/projects/items \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-11-02-row-17" \
  -d '{ "slug": "riverside-bakery", "fieldData": { "title": "Riverside Bakery" } }'

• Choose the key yourself, from 1 to 200 characters. A UUID, or an id from your own system, works well.
• Retrying with the same key and the same body returns the original result and does not create anything new.
• The same key with a different body returns 409 IDEMPOTENCY_CONFLICT.
• If the first request is still running, a retry returns 409 IDEMPOTENCY_IN_PROGRESS. Wait briefly and retry.
• Keys are scoped to the site and the operation, and expire after 24 hours.

Over MCP, pass the key as the idempotencyKey argument of the tool.

Optimistic concurrency

Pages, site-wide header and footer, and other content that people also edit in the dashboard use optimistic concurrency, so your script cannot silently overwrite someone's changes.

1. Read the resource and keep its timestamp: updatedAt for a page, contentUpdatedAt for globals.
2. Send it back as ifUnmodifiedSince with the write.
3. If the resource changed in between, the write fails with 409 CONFLICT and the current timestamp in details. Read again, merge your change, and retry.

{
  "ifUnmodifiedSince": "2026-11-02T08:00:00.000Z",
  "sections": [{ "id": "sec_hero_1", "type": "page-main-visual", "title": "Fresh bread daily" }]
}

The reference shows which operations take ifUnmodifiedSince.

Drafts first

Most writes change a draft, and a separate publish operation makes them live. Pages, globals and posts work this way. Collection items publish immediately unless you send publish: false. A failed or repeated write therefore rarely affects what visitors see.

Webhook deliveries

Kanorio may deliver the same event more than once, for example after a timeout or when someone resends it from the dashboard. Every delivery carries an X-Kanorio-Delivery id that stays the same across retries. Store the ids you have processed and return 200 for repeats. See Webhooks.