# transmute Developer Docs

## Guides

- [What is transmute?](https://transmute.documentationai.com/getting-started/overview.md): transmute is a stateless API that converts SWIFT MT messages to and from ISO 20022 (MX), normalizes both to canonical JSON, and validates them.
- [Create an Account](https://transmute.documentationai.com/getting-started/create-account.md): Sign up for the transmute portal with a passwordless email magic link, and understand how portal sessions work.
- [Get an API Key](https://transmute.documentationai.com/getting-started/api-keys.md): Create test and live API keys in the transmute portal. Keys are shown once, scoped, and capped at 20 per account.
- [Quickstart](https://transmute.documentationai.com/getting-started/quickstart.md): Convert a SWIFT MT940 statement to ISO 20022 camt.053, normalize it to canonical JSON, and validate it — three curls with a test key.
- [API Keys](https://transmute.documentationai.com/auth/api-keys.md): How transmute bearer authentication works — key format, storage model, and the uniform 401/403 behavior.
- [Test vs Live Keys](https://transmute.documentationai.com/auth/test-vs-live.md): Test keys are for trying the API: a one-time allowance of 250 requests per account, never billed. Live keys run production against your plan's monthly quota. The exact rules, including which statuses count.
- [Rotating Keys](https://transmute.documentationai.com/auth/rotating-keys.md): transmute has no in-place rotate operation — rotation is create-new, deploy, revoke-old. The honest procedure, including what happens on revocation.
- [Scopes](https://transmute.documentationai.com/auth/scopes.md): Every API key carries a scope list controlling which routes it may call. Six core scopes are granted by default; elevated scopes are opt-in.
- [IP Allowlists](https://transmute.documentationai.com/auth/ip-allowlists.md): Pin an API key or OAuth client to a set of source IP ranges (CIDRs). Requests from anywhere else get a 403, even with the correct key.
- [OAuth Client Credentials](https://transmute.documentationai.com/auth/oauth-client-credentials.md): The short-lived-token alternative to API keys — RFC 6749 client-credentials grant minting 15-minute ed25519 JWTs, verifiable offline via JWKS.
- [Convert](https://transmute.documentationai.com/guides/convert.md): POST /v1/convert — SWIFT MT ↔ ISO 20022 conversion. Request forms, from/to precedence, options, response envelope, XML/plain output, and paging.
- [Normalize](https://transmute.documentationai.com/guides/normalize.md): POST /v1/normalize — parse any supported MT or MX message into one canonical JSON shape, so your application handles a single format.
- [Validate](https://transmute.documentationai.com/guides/validate.md): POST /v1/validate — syntax and schema validation with structured findings. Message problems come back as findings in a 200, not as errors.
- [Formats](https://transmute.documentationai.com/guides/formats.md): GET /v1/formats — the live registry of supported message formats, versions, and conversion pairs. Always trust this endpoint over any static list.
- [Enrich](https://transmute.documentationai.com/guides/enrich.md): POST /v1/enrich — batch-check IBANs, BICs, currency codes and ISO 20022 external codes against registry data; get validity, normalized forms and derived facts.
- [Idempotency](https://transmute.documentationai.com/guides/idempotency.md): Opt-in safe retries with the Idempotency-Key header — 24-hour replay cache, conflict detection, and the privacy trade-off made explicit.
- [Batch & Jobs](https://transmute.documentationai.com/guides/batch-and-jobs.md): POST /v1/convert/batch — convert many messages asynchronously, poll the job for results or get a signed webhook, with encrypted short-TTL storage.
- [Webhooks](https://transmute.documentationai.com/guides/webhooks.md): Get a signed job.completed event instead of polling — endpoint registration, HMAC-SHA256 signature verification, retries, and auto-disable rules.
- [Accounting Connections](https://transmute.documentationai.com/guides/connections.md): Connect an accounting platform via OAuth2 so converted files are delivered there automatically — with an honest statement of what platforms allow.
- [Go SDK](https://transmute.documentationai.com/sdks/go.md): The official Go client — typed requests and responses generated from the OpenAPI spec, plus a webhook signature verifier.
- [TypeScript SDK](https://transmute.documentationai.com/sdks/typescript.md): The official TypeScript client — fully typed against the OpenAPI document, for Node.js and edge runtimes, with a webhook signature verifier.
- [Python SDK](https://transmute.documentationai.com/sdks/python.md): The official Python client — generated models with a convenience wrapper, OAuth helpers, and a webhook signature verifier.

## Reference

- [Errors Overview](https://transmute.documentationai.com/errors/overview.md): Every transmute error is RFC 9457 application/problem+json with a type URI from a closed catalog. The shape, the catalog, and how to handle errors.
- [Warnings Registry](https://transmute.documentationai.com/warnings.md): The closed registry of conversion warning codes. Every lossy or assumed step in a conversion surfaces as one of these — nothing is dropped silently.
- [Response Headers](https://transmute.documentationai.com/reference/headers.md): Every header the transmute API sets — request correlation, rate limit, quota, warnings, paging, and idempotency indicators.
- [Rate Limits & Quotas](https://transmute.documentationai.com/reference/rate-limits-and-quotas.md): Two separate mechanisms — a per-second token bucket and a monthly conversion quota — with different headers, different 429s, and different fixes.
- [Spend Caps & Usage Alerts](https://transmute.documentationai.com/reference/spend-caps-and-alerts.md): Opt-in controls for paid plans — block overage entirely or cap what it can cost, and get email alerts as you approach or reach your included volume.
- [invalid-input](https://transmute.documentationai.com/errors/invalid-input.md): 400 Bad Request — The request itself could not be processed: a malformed JSON envelope, a missing `to` or `message`, an unknown option value, a bad query parameter, an .
- [unsupported-format](https://transmute.documentationai.com/errors/unsupported-format.md): 422 Unprocessable Content — The source format (given or auto-detected) is not one this deployment supports.
- [unsupported-conversion](https://transmute.documentationai.com/errors/unsupported-conversion.md): 422 Unprocessable Content — Both formats are individually supported, but the requested `from` → `to` pair is not a supported conversion (some formats are normalize-only, and file.
- [charset](https://transmute.documentationai.com/errors/charset.md): 422 Unprocessable Content — The message contains characters that cannot be represented — or transliterated under the selected profile — in the target format's character set (the .
- [message-too-large](https://transmute.documentationai.com/errors/message-too-large.md): 413 Content Too Large — The request body exceeds the synchronous limit of **2 MiB** (or 16 MiB for `POST /v1/convert/batch`).
- [unauthorized](https://transmute.documentationai.com/errors/unauthorized.md): 401 Unauthorized — Authentication failed.
- [forbidden-scope](https://transmute.documentationai.com/errors/forbidden-scope.md): 403 Forbidden — The credential is valid but lacks the [scope](/auth/scopes) this route requires.
- [forbidden-ip](https://transmute.documentationai.com/errors/forbidden-ip.md): 403 Forbidden — The credential is valid but was presented from a client IP outside its configured [IP allowlist](/auth/ip-allowlists).
- [rate-limited](https://transmute.documentationai.com/errors/rate-limited.md): 429 Too Many Requests — Your per-second token bucket is exhausted.
- [quota-exceeded](https://transmute.documentationai.com/errors/quota-exceeded.md): 429 Too Many Requests — the pool your credential draws from is exhausted: the one-time 250-request test allowance, or a hard-stop plan's monthly quota.
- [idempotency-conflict](https://transmute.documentationai.com/errors/idempotency-conflict.md): 409 Conflict — This `Idempotency-Key` was already used with a **different** request body.
- [not-found](https://transmute.documentationai.com/errors/not-found.md): 404 Not Found — The resource does not exist **for your tenant**.
- [batch-unavailable](https://transmute.documentationai.com/errors/batch-unavailable.md): 503 Service Unavailable — The batch/jobs/connections subsystem is not available on this deployment (its encrypted job storage is not configured).
- [connection-failed](https://transmute.documentationai.com/errors/connection-failed.md): 422 Unprocessable Content — Delivery to your accounting connection could not proceed because the connection is broken — typically a revoked or expired OAuth authorization.
- [provider-error](https://transmute.documentationai.com/errors/provider-error.md): 502 Bad Gateway — The accounting platform's API failed while we were delivering your file — their outage, surfaced honestly instead of swallowed.
- [internal](https://transmute.documentationai.com/errors/internal.md): 500 Internal Server Error — Something failed on our side.
- [portal-email-rejected](https://transmute.documentationai.com/errors/portal-email-rejected.md): 422 Unprocessable Content — The signup/sign-in email address was rejected by deliverability screening: disposable-domain or undeliverable addresses cannot create accounts.
- [portal-forbidden](https://transmute.documentationai.com/errors/portal-forbidden.md): 403 Forbidden — Your portal session does not permit this action.
- [portal-signup-rate](https://transmute.documentationai.com/errors/portal-signup-rate.md): 429 Too Many Requests — Signup/sign-in velocity limits were hit: magic-link requests are limited to 3 per address per 15 minutes, and new free-account creation is velocity-li.
- [portal-unavailable](https://transmute.documentationai.com/errors/portal-unavailable.md): 503 Service Unavailable — A portal dependency (email delivery or screening) is not available; sign-in cannot proceed right now.
- [Support](https://transmute.documentationai.com/support.md): How to reach transmute support, and what to include so we can help fast.
- [API Terms](https://transmute.documentationai.com/legal/api-terms.md): Terms of service for the transmute API.