Source: docs/integration/idempotency.md

Idempotency

Capability imports

Every POST /v1/capabilities/import request requires an Idempotency-Key

header. Generate one key for a single logical import and reuse that exact key

when retrying the same request.

-H "Idempotency-Key: capability-import-$(date +%s)"

A repeated import with the same key returns the previous result and includes

Idempotency-Replayed: true; it does not create a second capability revision.

Use a new key only for a new logical import, such as one containing a revised

manifest.

Host operation results

Host-owned operation reports to

POST /v1/conversations/{conversationId}/operation-results require an

Idempotency-Key. The key is scoped to the account and stored with a request

hash. Reusing it with a different interaction, operation, or status returns

409 IDEMPOTENCY_KEY_REUSED.

Forgium does not execute or retry the host operation. The host remains

responsible for authorization, concurrency, mutation idempotency, and replay

protection before reporting a terminal status.