Deduplication and Idempotency - SafeFetch

`dedupe`

dedupe deduplicates semantically identical actions in a 24-hour window.

Scope: account + key
Ignores already failed actions
If matched, API returns existing action with deduplicated: true

Typical use cases

Prevent duplicate invoice processing
Avoid repeated outbound notifications
Suppress duplicate user-triggered operations

`Idempotency-Key` header

Idempotency-Key deduplicates repeated create requests in a 24-hour window.

Scope: account + header value
Works even if body is retried by the client unchanged
Returns existing action with deduplicated: true

Difference

dedupe
Idempotency-Key

Business-level dedupe: “these actions mean the same thing”.

cURL examples

curl -X POST http://localhost:3000/v1/actions \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/work",
    "body": {"invoice_id":"inv_123"},
    "dedupe": "invoice:inv_123"
  }'

curl -X POST http://localhost:3000/v1/actions \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Idempotency-Key: req-2026-03-16-001" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/work",
    "body": {"invoice_id":"inv_123"}
  }'