API · Conventions
Dry run
Preview a mutation's effects without committing
Last updated
Every mutation in Matter accepts ?dry_run=true. The endpoint computes the resource it would create (or update), the cascading state changes it would trigger, and the fee estimate — without persisting anything or kicking off downstream side effects.
curl -X POST "https://api.mattermode.com/v1/entities?dry_run=true" \
-H "Authorization: Bearer $MATTER_KEY" \
-d '{ "intent": "delaware_c_corp", "name": "Acme, Inc." }'The response shape matches a real call:
{
"id": null,
"object": "entity",
"preview": true,
"state": "would_be_draft",
"would_emit_events": ["entity.created"],
"fee_estimate": { "currency": "usd", "total": 12500 },
"name_availability": "available"
}Use cases
| Scenario | Why dry-run |
|---|---|
| Quote builder | Get a fee estimate without committing. |
| Agent rehearsal | Tier-2 agents can preview a tier-3 action's effects before requesting authorization. |
| CI smoke tests | Assert response shape on production-style payloads without creating fixture entities. |
| Pre-submit validation | Catch missing-fields or jurisdiction-rule violations before the user clicks submit. |
Combinations
?dry_run=true&expand[]=registered_agentworks as expected — the preview includes expanded references it would create.Idempotency-Keyis ignored on dry runs (there's nothing to memoize).- Webhooks are not fired on dry runs.
Related
- Idempotency
- Test mode — also free, but actually creates state.
Tier-1 (observe) tokens can call dry-run on any mutation endpoint. This is the canonical way for read-only agents to surface what a higher-tier agent could do.