Idempotency keys and dry runs

Idempotency keys

Networks fail and agents retry. An idempotency key makes sure a retried change happens once.

Pass idempotencyKey (8 to 200 characters, unique per change) on any action that changes something:

{
  "text": "We just shipped dark mode.",
  "idempotencyKey": "post-2026-11-03-dark-mode"
}

• Same key, same input: you get the first call’s result back, and nothing runs again.
• Same key, different input: IDEMPOTENCY_KEY_REUSED. Use a new key for a new change.
• Same key while the first call is still running: IDEMPOTENCY_IN_PROGRESS with retryAfterSeconds. Retry with the same key.
• If the call fails, the key is released, so retrying with it runs the action again.

publish_now (posts.publish_now) requires a key, so a post can never go out twice. For everything else it’s optional but recommended in scripts and agents. Reads ignore it.

Good keys come from your own data: a row id, a hash of the content, or a UUID you store with the job.

Dry runs

Pass dryRun: true on any change to see exactly what would happen, with nothing changed and no credits spent:

{
  "ok": true,
  "summary": "Dry run: Schedule a post would run on @yourhandle with this input. Nothing was changed.",
  "data": {
    "capabilityId": "posts.schedule",
    "account": "yourhandle",
    "input": { "text": "…", "scheduledAt": "2026-11-03T09:00", "timezone": "Europe/London" }
  },
  "dryRun": true
}

A dry run still checks your credential, scope, account, plan and input, so it’s a cheap way to test a request before running it for real. It doesn’t check for conflicts that only appear when the change runs (for example a time slot taken in the meantime).

In the CLI, --dry-run does the same.