Dry-Run Mode
How the X-Sarudo-Dry-Run header works, which endpoints respect it, and how to preview side-effecting actions safely.
What Dry-Run Mode Is
Dry-run mode lets any side-effecting Sarudo endpoint — the ones that send emails, post to social, create documents, update CRM records, publish to your CMS — return a preview of what it would do instead of actually doing it. You activate it by setting the `X-Sarudo-Dry-Run: true` header on the request. The endpoint validates the inputs, computes the plan, and returns a response showing exactly what would have happened, with no side effects. This is the safest way to build or debug a workflow that will eventually do real work.
The header is flexible about what counts as "true" — `true`, `1`, `yes`, and `on` all activate dry-run mode. Case is not significant.
What a Dry-Run Response Looks Like
Every dry-run response has a consistent shape: `{status: "ok", dry_run: true, would_do: "<human-readable description>", inputs_ok: <true|false>, preview: { ... endpoint-specific preview fields ... }}`. The `would_do` field is a one-line English summary ("would send email to alex@example.com with subject 'Weekly Update'"). The `inputs_ok` boolean tells you whether the inputs passed validation — if false, the preview shows what validation caught. The `preview` object carries endpoint-specific detail: an email preview includes the recipient, subject, and first lines of body; a sheets append preview includes the range, row count, and sample first row; a Google Docs preview includes the section count and types.
A dry-run response for an email send
What the header does to a real endpoint call.
Which Endpoints Respect the Header
Dry-run is wired on every endpoint where running it for real would have a visible external consequence. This includes: `/email/send` and all other email write endpoints; `/publer/post` (social publishing); `/social/post` (honest 501 — dry-run returns the same 501); `/payment/checkout`, `/payment/invoice`, `/payment/refund`; `/integrations/sheets/append` and `/integrations/sheets/update`; `/integrations/google_docs/create`; most of `/calendar/*` (send-invitation paths); and the publish-webhook endpoints in the Content Calendar Pipeline. Read-only endpoints (/crm/contacts GET, /seo/*, /data/query, /web/search) ignore the header — there is nothing to dry-run when the operation is read-only. Endpoints that are side-effecting but not yet dry-run-aware (/crm/contacts POST, /data/store, /integrations/sheets/create) simply fall through and execute normally; the preview endpoint in the reliability layer flags these by name so you know which ones are not yet covered.
If you are not sure whether an endpoint respects the dry-run header, just add the header and try it. Supporting endpoints return a `dry_run: true` response; non-supporting endpoints execute normally. There is no scenario where adding the header breaks something that would otherwise have worked.
When to Use Dry-Run
Three situations where dry-run pays off. First, when you are building or modifying a workflow — every HTTP node in the new workflow can be previewed before you activate, so you see exactly what payloads would fly, whether they pass validation, and whether the computed inputs look right. Second, when you are debugging a workflow that did something unexpected — re-run the last execution in dry-run mode and inspect the plan. Third, when a client (or your AI employee, acting on a client request) wants a "what would this actually do?" sanity check before committing — "show me what the email reminder would look like if I fire it now" is a dry-run by another name.
Dry-Run at the Workflow Level
You can run an entire workflow in dry-run mode, not just a single endpoint. Every HTTP node in the workflow will have the X-Sarudo-Dry-Run header set automatically, so the whole chain executes without side effects, and you get a concatenated preview of what each step would have done. This is the "flight check" mode — useful before activating a new scheduled workflow for the first time, or before running a one-off workflow against real data when you want the confidence of "I saw it not do damage" first.
Recommended pattern for new workflows: build it, dry-run it once on real data, review the preview, activate. The dry-run catches the class of mistake that would otherwise only surface in production.