> ## Documentation Index
> Fetch the complete documentation index at: https://kavenio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

Idempotency prevents a retried mutation from creating the same resource or
provider side effect twice. Support is endpoint-specific. Use the header named
by the endpoint reference and reuse its value only for retries of the same
logical request.

## Creating posts

`POST /v1/posts` uses `X-Request-Id` for request replay protection. Kavenio
scopes the key to the authenticated subject and organization, hashes the
canonical request body, and keeps the completed result for five minutes.

```bash theme={null}
curl --request POST "https://api.kavenio.com/v1/posts" \
  --header "Authorization: Bearer $KAVENIO_API_KEY" \
  --header "Content-Type: application/json" \
  --header "X-Request-Id: post_20260716_launch_01" \
  --data '{
    "profileId": "aaaaaaaaaaaaaaaa",
    "isDraft": true,
    "content": "Release notes"
  }'
```

Within the five-minute window:

* the same request ID and the same body return the same post; if publishing is
  still progressing, the response can contain the post's newer state;
* the same request ID with a different body returns `VALIDATION_ERROR`;
* a matching request that is still in progress returns `CONFLICT`;
* keys are limited to 255 characters.

The JavaScript SDK generates a request ID for each `posts.create()` call. When
your own retry wrapper may repeat a call, generate the ID once and pass the same
value to every attempt:

```ts theme={null}
const requestId = crypto.randomUUID();

const post = await retryTransiently(() =>
  client.posts.create(payload, { requestId }),
);
```

Generating a new ID inside the retry callback creates a new logical request and
does not provide replay protection.

## Other mutation endpoints

Some provider-backed mutation endpoints use `Idempotency-Key` instead. When an
endpoint requires that header, send a unique value for the first attempt and
reuse it for retries of the same request body. Do not reuse a completed key for
a different operation.

## Provider publishing is a separate boundary

API request idempotency prevents duplicate Kavenio resources. It does not prove
that every provider accepts an idempotency key for the final publish call.

Kavenio uses provider-native publish idempotency where the adapter and provider
support it. When a non-idempotent provider may have accepted a publish but the
result is missing, Kavenio marks the target `action_required` instead of
blindly publishing it again. Inspect the target state and reconcile an unknown
provider outcome before retrying.