Idempotency | everyn

How Everyn clients safely retry create requests without duplicating product work.

Idempotency keeps network retries from creating duplicate datasets, job specs, runs, exports, alert rules, webhook endpoints, organizations, API keys, or invitations. Everyn treats the idempotency key as part of the create-operation contract.

Idempotency rules

Create-style routes that require Idempotency-Key:

Route	Purpose
`POST /v1/dataset-uploads`	Create a dataset upload session and enqueue intake.
`POST /v1/job-specs`	Create a reusable job spec.
`POST /v1/runs`	Create a run from a dataset and job spec.
`POST /v1/runs/{runId}/retry`	Create a retry run with lineage.
`POST /v1/runs/{runId}/exports`	Create a self-starting export.
`POST /v1/webhook-endpoints`	Create a webhook endpoint.
`POST /v1/alert-rules`	Create an alert rule.
`POST /v1/organizations`	Create an organization through the admin API.
`POST /v1/organizations/{organizationId}/api-keys`	Create an organization-owned API key.
`POST /v1/organizations/{organizationId}/invitations`	Create an organization invitation.

Example:

curl -sS -X POST "$EVERYN_BASE_URL/v1/runs" \
  -H "Authorization: Bearer $EVERYN_API_KEY" \
  -H "Idempotency-Key: run-preview-20260707-leads-v1" \
  -H "Content-Type: application/json" \
  --data '{
    "datasetId": "ds_...",
    "jobSpecId": "js_...",
    "scope": { "type": "limit", "count": 25 }
  }'

Recovery rules:

Situation	Client behavior
Timeout before response	Retry the same request with the same `Idempotency-Key`.
Same key, same body	Expect the same logical operation rather than duplicate product work.
Same key, changed body	Expect `409 idempotency_conflict`; choose a new key only if the changed request is truly a new operation.
New run or retry intended	Create a new idempotency key and make the retry or follow-up run explicit.

See the API quickstart for run creation and API errors for 409 recovery.