Run creation is asynchronous, so a client can lose the response after Infragrid has already accepted the work. Add X-Idempotency-Key to make retries recover the original run.
How keys are bound
Infragrid binds an idempotency record to:
- the workspace
- the API credential
- the route
- the normalized request body
A retry with the same key and equivalent body returns the stable original result. Reusing the key with a different body returns 409 Conflict.
A key is not global deduplication. The same string used by a different credential or route has a separate idempotency scope.
Choose a key
Use a durable application identifier that represents one logical mutation.
Keys must contain 1–255 printable ASCII characters without spaces. Do not include secrets or personal data.
SDK behavior
The SDKs retry transient create failures only when an idempotency key is present. Without one, a create request is attempted once.
Blueprint runs
The same behavior applies to POST /v1/blueprints/{blueprint_id}/runs. Include the pinned revision and inputs in your logical operation design so a changed payload cannot silently reuse an earlier run.
Persist both your application job ID and the returned Infragrid run ID. The application ID protects creation; the run ID supports direct recovery and support diagnostics.
