An operation that changes something is a POST, a PATCH or a DELETE,
needs write in its own family, and differs from a read in three ways.
It requires an Idempotency-Key request header. Choose one value per
change you intend to make, and send that same value again if you have to
retry. Commune records the answer your first attempt produced and replays
it rather than making the change a second time; a replayed response carries
Idempotent-Replay: true and is otherwise identical to the original. A key
is remembered for 24 hours, per credential.
Reusing a key for a different request answers 409 rather than replaying
the wrong answer. Two requests count as the same request when the operation,
the path, the query string, the body and the contract version all match.
It is counted against the write rate limit budget. See Rate limits
above.
It publishes an event, carrying your credential in the envelope's
actor and your Idempotency-Key in idempotency_key. That lets a
consumer tell a change your integration made from one a creator made in
Commune, and collapse the events one retried write produced. If the same
integration also consumes events, the event your write publishes is
delivered back to you: skip the ones whose idempotency_key you issued, or
your integration will answer itself. See Webhooks.
One key per change you mean to make:
curl -X POST https://api.usecommune.com/newsletters/the-weekly/tags \
-H "Authorization: Bearer $COMMUNE_API_KEY" \
-H "Commune-Version: 2026-08-26" \
-H "Idempotency-Key: 0b6f8e2a-3c1d-4a97-b5e4-7d2c9f1a8e30" \
-H "Content-Type: application/json" \
-d '{"name": "Founding member"}'
Sent again with the same key and the same body, the request is answered from the record of the first one and changes nothing:
HTTP/1.1 201 Created
Idempotent-Replay: true