Public API
Operations
Idempotency
Use Idempotency-Key on job creation, merge creation, and recipe runs so retries do not create duplicates.
Base route
https://api.filemorf.com/api/public
Auth
Bearer API key created from the workspace.
Delivery model
Signed uploads, queued jobs, retained artifacts, refreshable URLs.
Retry safety
Use Idempotency-Key on every create-like write
The API will reuse an earlier resource when the key and payload match, or return a conflict when the key is reused with a different payload.
- POST /jobs supports Idempotency-Key and fingerprints the full job payload.
- POST /merge supports Idempotency-Key and fingerprints the ordered files list and options.
- POST /recipes/:id/runs supports Idempotency-Key scoped to the recipe plus retained input artifact.
- Reusing the same key with a different payload returns HTTP 409 instead of creating another resource.
Recommendations
Build deterministic keys from your source system
Tie the idempotency key to the source record that should own the FileMorf resource, not to the transient request attempt.
- Use business identifiers like contract-483-ocr-v1 or import-batch-2026-03-25-12 instead of random UUIDs when retry behavior matters.
- Keep the key stable across retries of the same operation.
- Never reuse the same key for a different file payload or different target workflow.