Idempotency

Networks fail after a request was sent and before its answer arrived. Retrying a write blindly could then create a second lead, start a second discovery run, or run the same import twice. An Idempotency-Key makes the retry safe: the API runs the request once and answers every retry with the same result.

curl -X POST https://api.dmhero.ai/v1/leads \
  -H "Authorization: Bearer $DMHERO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c9a2e-3b4d-4c5e-8f9a-0b1c2d3e4f5a" \
  -d '{ "ig_handle": "jane.doe" }'

The rules

• Generate one key per logical action, a UUID v4 is ideal, and reuse it for every retry of that action. A new action gets a new key.
• Keys are 1 to 255 printable ASCII characters. Keys starting with mcp: are reserved for the MCP server.
• A key lives 24 hours. After that the same key starts a new request.
• A key belongs to the API key that used it and to that key's rotations: a retry after you rotated the key still deduplicates, while another key of the same workspace can never replay your result.
• A retry must be the same request: same operation, path and body, from an API key with the same reps (a rotated key keeps them). The same Idempotency-Key with a different request answers 422 API_IDEMPOTENCY_MISMATCH_422.
• GET and DELETE need no key: they are naturally safe to repeat (a second DELETE answers 404).

What a retry gets back

Validation, authentication and rate limit refusals happen before the key is recorded, so a malformed request never uses up a key.

When the outcome is unknown

A few operations act on the world outside DM Hero, where a half finished attempt cannot be undone: reserving discovery tokens, starting a bulk change, an import or an export. If our server stopped after acting and before recording the result, we cannot know whether it acted. A retry with the same key then answers 409 API_IDEMPOTENCY_OUTCOME_UNKNOWN_409 with claimed_at, the time the first attempt started, and does not act again.

Reconcile, then decide:

• A discovery run: list GET /v1/discovery/runs?created_after= with claimed_at.
• A job (import, export, bulk change): list GET /v1/jobs.

If nothing happened, send the request again with a new key. A new key is your explicit decision to try again; the API never makes it for you.

Which operations take a key

Required operations refuse a request without a key (400 API_IDEMPOTENCY_KEY_REQUIRED_400). Accepted means optional but recommended for anything you retry automatically.