Idempotency

curl --fail-with-body https://app.ghostgtm.ai/api/v1/definitions \
  -H "Authorization: Bearer $GHOST_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: integration-stage-create-001' \
  --data '{"name":"Integration stage","moduleKey":"customers","entityKinds":["account"],"valueType":"enum","enumValues":[{"label":"New"},{"label":"Qualified"}],"reason":"Track qualification from our integration"}'

• Generate a new key for every logical request. Reuse it only when retrying that same request.
• 1–128 visible ASCII characters. Anything else is rejected with 400.
• A replay returns the original response, even if later writes changed the resource. It does not re-apply the mutation.
• The same key with different input, or a different action, returns 409.
• Receipts are scoped to the workspace and the key, and are retained without expiry.

Identical value assignments without a key are also no-ops when actor, value, reason, evidence, source and pinning all match the current assignment.

Long-running operations

POST /operations returns a receipt with a status of queued, running, succeeded, failed, needs_review, canceled or outcome_unknown. An interrupted write may have applied effects - when the outcome is unknown, inspect the target before submitting again. A failed batch can contain successful items; read its result rather than repeating the whole batch.