Quickstart

1. Create an API key #

Transmutify authenticates every API request with an organization-scoped bearer token. Create one under API Keys in the dashboard, then pass it in the Authorization header. See Authentication for details.

2. Pick a schema and a provider #

A transformation always targets one of your schemas. To prepare the mapping with AI you also need a provider. List both and note their id values or simply copy the ID from the Dashboard.

curl 'https://api.transmutify.io/v1/schemas' \
  -H 'Authorization: Bearer <api-key>'

The same pattern works for GET /providers. Omit provider_id later if you want to supply the mapping yourself instead of using AI.

3. Initialize a transformation run #

curl -X POST 'https://api.transmutify.io/v1/transformations/file' \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "schema_id": "<schema-id>",
    "provider_id": "<provider-id>",
    "filename": "employees.csv",
    "output_format": "json",
    "notify_url": "https://example.com/webhooks/transmutify"
  }'

The response contains the run id and pre-signed upload instructions, plus the hosted review_url:

{
  "id": "9b2e1f6c-8e6d-4a3b-9c1f-7d2e5a8b3c4d",
  "status": "awaiting_upload",
  "stage": "review",
  "input_source": "upload",
  "schema_id": "<schema-id>",
  "review_url": "https://review.transmutify.io/reviews/…secret…",
  "upload": {
    "url": "https://storage.example.com/…signed…",
    "headers": { "Content-Type": "text/csv" },
    "method": "PUT",
    "expires_at": "2026-01-15T13:00:00Z"
  }
}

4. Upload the source file #

Send the file with the returned method and headers. The URL expires after 30 minutes; supported extensions are csv, tsv, txt, xlsx up to 50 MB.

curl -X PUT '<upload.url>' \
  -H 'Content-Type: text/csv' \
  --data-binary @employees.csv

5. Open the hosted review #

Transmutify inspects the file and asks your AI provider to prepare a mapping. Open the hosted review_url returned by the create or transformation detail response. The Review UI handles review readiness, review failures, mapping edits, data validation, and approval. Poll the run only when you need to refresh your own integration state; transformation detail responses include review_state, review_approved_at, review_canceled_at, and review_expires_at:

curl 'https://api.transmutify.io/v1/transformations/<run-id>' \
  -H 'Authorization: Bearer <api-key>'

Not happy with the mapping? Reviewers can regenerate or override the mapping directly in the hosted review flow.

6. Approve the review #

Once the mapping and data look right, the reviewer approves directly in the hosted Review UI. Transmutify locks the effective mapping and saved data edits, moves the run to the final stage, and starts final processing for the first 100,000 uploaded records. The Review UI keeps manual row review separate and shows up to 1,000 rows for browsing and editing.

7. Download the result #

When the final run completes successfully, the transformation.finished webhook delivers the pre-signed download_url straight to your notify_url. Poll the run until status reaches completed or failed, then read download_url or error from the response. Output files are retained for 7 days (file_retention_until tells you exactly how long).

Production checklist #

• Store the returned run id and pass your own correlation keys in metadata.
• Hand reviewers the signed review_url; review actions are handled inside the hosted Review UI.
• Prefer webhooks and review callback URLs for the normal flow. Use GET /transformations/{id} only to refresh state, inspect failures, or refresh a download_url.
• Verify the webhook secret and dedupe deliveries by X-Transmutify-Id plus X-Transmutify-Event.
• Download and persist the final artifact before the retention window expires.