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`	A verified human creates a reusable Job through a browser session.
`POST /v1/job-specs/{jobSpecId}/fork`	A verified human forks an exact Job version.
`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:

This machine-key example creates a Run from an existing human-authored Job. A machine key cannot claim or replay a Job-authoring idempotency receipt, even if it has job_specs:write.

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.
Job authoring after membership revocation	The human must regain current workspace write access; a matching old key does not bypass authorization.
Historical machine Job-authoring receipt	A human must review the Job and use a new key; the old receipt cannot be replayed as human authoring.

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