> For the complete documentation index, see [llms.txt](https://api-reference.usecommune.dev/llms.txt)

# Writes

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.

## Example
One key per change you mean to make:

```shell
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
HTTP/1.1 201 Created
Idempotent-Replay: true
```

