Core concepts
Schemas, providers, transformation runs, stages, and dry runs — the building blocks every Transmutify integration is made of.
Schemas
A schema describes the output you want: a set of target fields, each with a description, a data_type, and an is_required flag. Field descriptions matter — they are what the AI reads when deciding which source column maps to which target field. Schemas are managed in the dashboard and listed via GET /schemas.
Providers
A provider is an AI configuration your organization registered: a provider key (anthropic, openai, xai, gemini, or openrouter), a model, and your own API credentials for it. Pass a provider's id as provider_id when creating a run to have it prepare the mapping. List them via GET /providers.
Transformation runs
A run tracks one transformation end to end. It carries the target schema, the input source (upload, raw, or image), the effective mapping rule, progress counters, and — once finished — the download URL for the produced artifact.
Lifecycle statuses
| Status | Meaning |
|---|---|
awaiting_upload | The run was initialized for a file upload and is waiting for the source file to arrive. |
queued | Work is scheduled and will start shortly. |
processing | Transmutify is inspecting input, preparing review data, or transforming rows. |
completed | The current stage finished successfully. In the final stage this means the output artifact is ready. |
failed | Something went wrong. The error payload on the run describes what and whether a retry can help. |
The boolean terminal field tells you whether the run has reached a final state — handy as a stop condition when polling.
Stages: review and final
Runs move through review and final stages. In the review stage, reviewers use the hosted Review UI to confirm mappings, validate generated rows, save data edits, approve, or cancel. Structured file reviews start with Mapping and then Validate Data; raw and image reviews open directly on Validate Data because the provider already generated the output rows.
Approval locks the effective mapping and saved data edits, moves the run to the final stage, and starts output processing. The final stage is the only place customer-consumable artifacts and download URLs are created.
Runtime limits
| Area | Configured limit |
|---|---|
| Structured uploads | CSV, TSV, TXT, XLSX up to 50 MB. |
| Image uploads | JPG, JPEG, PNG, WEBP up to 10 MB, with schemas up to 20 fields. |
| Raw content | Up to 50,000 characters, with schemas up to 20 fields. |
| Schemas | Up to 80 fields overall. |
| Processing | Transforms up to 100,000 uploaded rows. |
| Hosted Review | Links expire after 24 hours. Reviewers can browse up to 1,000 rows, with 100 rows per page. |
Dry runs
Set dry_run: true when creating a run to wire up and test your integration. A dry run does not use your real data: the uploaded file (or the submitted content on the raw flow) is never read. Transmutify generates synthetic, schema-shaped example values instead — no AI provider is called and no review quota is consumed.
Because a dry run follows the exact same lifecycle and returns the same response shape as a real run, it is ideal for building the integration, staging environments, and automated tests. It is not meant to validate real mappings or output — switch dry_run off once the wiring works.