File Transmute API

A simple REST API for server-side conversions (PDF↔Office, table extraction, and more). Authenticate with an API key, create a job, stream progress, and download the result — or receive a signed webhook when it's done.

Authentication

Create a key in your account dashboard, then send it as an X-API-Key header. Keys are shown once — store them securely. The base URL is https://filetransmute-api.fly.dev.

Quickstart

cURL

# 1. Create a job (authenticate with your API key)
curl -X POST https://filetransmute-api.fly.dev/v1/jobs \
  -H "X-API-Key: ak_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "tool=pdf-to-excel" \
  -F "file=@invoice.pdf"
# → { "id": "job_…", "status": "queued", "events_url": "/v1/jobs/job_…/events" }

# 2. Poll status, then download
curl https://filetransmute-api.fly.dev/v1/jobs/job_… -H "X-API-Key: ak_live_…"
curl -o out.xlsx https://filetransmute-api.fly.dev/v1/jobs/job_…/download

JavaScript

const form = new FormData();
form.append("tool", "pdf-to-excel");
form.append("file", fileInput.files[0]);

const res = await fetch("https://filetransmute-api.fly.dev/v1/jobs", {
  method: "POST",
  headers: { "X-API-Key": process.env.QUICKCONVERT_KEY, "Idempotency-Key": crypto.randomUUID() },
  body: form,
});
const { id } = await res.json();

// Stream progress
const es = new EventSource(`https://filetransmute-api.fly.dev/v1/jobs/${id}/events`);
es.onmessage = (e) => {
  const job = JSON.parse(e.data);
  if (job.status === "done") {
    es.close();
    window.location = `https://filetransmute-api.fly.dev/v1/jobs/${id}/download`;
  }
};

Python

import requests, uuid

key = {"X-API-Key": "ak_live_…", "Idempotency-Key": str(uuid.uuid4())}
with open("invoice.pdf", "rb") as f:
    r = requests.post("https://filetransmute-api.fly.dev/v1/jobs",
                      headers=key, data={"tool": "pdf-to-excel"}, files={"file": f})
job = r.json()

# poll until done
import time
while True:
    s = requests.get(f"https://filetransmute-api.fly.dev/v1/jobs/{job['id']}").json()
    if s["status"] in ("done", "failed"):
        break
    time.sleep(0.5)

out = requests.get(f"https://filetransmute-api.fly.dev/v1/jobs/{job['id']}/download")
open("out.xlsx", "wb").write(out.content)

Endpoints

POST/v1/jobsCreate a conversion job (multipart: file, tool). Supports Idempotency-Key.

GET/v1/jobs/{id}Job status, progress, and output name.

GET/v1/jobs/{id}/eventsServer-Sent Events stream of live progress.

GET/v1/jobs/{id}/downloadDownload the finished file.

GET/v1/formatsSupported server tools and which are available.

GET/v1/usageYour org's jobs, bytes processed, and credits spent.

GET/v1/api-keysList your API keys.

POST/v1/api-keysCreate a key (secret shown once).

GET/v1/webhooksList webhook endpoints.

POST/v1/webhooksRegister a webhook (signing secret shown once).

Idempotency

Pass an Idempotency-Key header on POST /v1/jobs. A retry with the same key returns the original job (and never charges twice) — safe for network retries.

Webhooks

Register an endpoint at POST /v1/webhooks to receive job.completed and job.failed events. Each delivery is signed with your webhook secret in the X-FileTransmute-Signature header — verify it before trusting the payload:

import hmac, hashlib   # Node/Python pseudocode — verify the signature
# header: X-FileTransmute-Signature: sha256=<hex>
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, request.headers["X-FileTransmute-Signature"])

Rate limits

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. When exceeded you get 429 with a Retry-After header.

Full interactive reference (OpenAPI / Swagger) is served at https://filetransmute-api.fly.dev/docs.