Sync

Most conversions take a few seconds. Instead of polling, you can keep the request open until the result is there.

Simple API: wait#

Add ?wait=N to POST /v1/convert, GET /v1/conversions/{id}, POST /v1/batches or GET /v1/batches/{id}. The request waits up to N seconds, at most 30. If the work is done by then, you get 200 with the result, otherwise 202 with the current state. Ask again with the same wait until it is done.

With Accept: application/octet-stream, a finished conversion comes back as the file itself:

curl -L "https://api.switchfile.io/v1/convert?wait=30" \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY" \
  -H "Accept: application/octet-stream" \
  -F [email protected] -F to=pdf \
  -o report.pdf

Files over 50 MB come as 303 See Other with the download URL in Location; curl -L and fetch follow it.

Jobs: the /sync prefix#

Every /v2 path also exists under /sync. These requests wait until the job or task is finished or has failed, up to 5 minutes:

GET /v2/jobs/{id}/wait and GET /v2/tasks/{id}/wait do the same without the prefix.

With "redirect": true in the job, POST /sync/v2/jobs answers with 302 to the first exported file, so a single request turns a URL into a converted download:

curl -L https://api.switchfile.io/sync/v2/jobs \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect": true,
    "tasks": {
      "import-1": {"operation": "import/url", "url": "https://example.com/report.docx"},
      "convert-1": {"operation": "convert", "input": "import-1", "output_format": "pdf"},
      "export-1": {"operation": "export/url", "input": "convert-1"}
    }
  }' \
  -o report.pdf

import { writeFile } from "node:fs/promises";

const res = await fetch("https://api.switchfile.io/sync/v2/jobs", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SWITCHFILE_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    redirect: true,
    tasks: {
      "import-1": { operation: "import/url", url: "https://example.com/report.docx" },
      "convert-1": { operation: "convert", input: "import-1", output_format: "pdf" },
      "export-1": { operation: "export/url", input: "convert-1" },
    },
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
await writeFile("report.pdf", Buffer.from(await res.arrayBuffer()));

If the job fails, or takes longer than 5 minutes, you get the job as JSON instead of the redirect.

When to use webhooks instead#

Waiting is simple, but it keeps a connection open per file. For long videos or many files at once, create the conversion without waiting and let a webhook tell you when it is done. Set your HTTP client's timeout above the wait you send, for example 40 seconds for wait=30.