Idempotency & upserts

Renza's write semantics are designed for forward-only clients — an agent (or a flaky script) should be able to push its current state repeatedly without tracking what already exists.

Idempotency keys

Any POST, PATCH, or DELETE may send an Idempotency-Key header with a UUID you generate. Renza records the first result and replays it for any retry with the same key for 24 hours — a timeout-and-retry can't create two decks.

curl https://api.renza.io/v1/decks \
  -H "Authorization: Bearer $RENZA_API_KEY" \
  -H "Idempotency-Key: 1f0e6f0c-6f6e-4b1a-9f3e-2b7c9d4a5e6f" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "title": "Q3 Board Deck" }'

The CLI exposes this as --idempotency-key on writes. Reusing a key with a different body is an idempotency_conflict.

Upsert by external_id

An external_id is a client-chosen id, unique per org, accepted anywhere a Renza id is. Create with one, and a later create with the same external_id updates the existing resource instead of duplicating it:

This is how an agent keeps one deck current across many runs:

renza import deck.html --external-id q3-board-deck   # run 1: creates
renza import deck.html --external-id q3-board-deck   # run 2: new version, same deck

And external_id works for lookups too: renza decks get q3-board-deck.

Partial updates, arrays, and metadata

• PATCH touches only the fields you send. Omit a field to leave it alone.
• Arrays replace fully. Send [] to clear, a full array to replace, or omit to keep.
• metadata merges. Include a key to set it, send null to delete that key, omit to leave it, or send {} to clear the map — so multiple integrations can share one metadata map without clobbering each other.