Without storage

With store=false, switchfile converts a file without storing it. The file comes in the request, the result goes back in the response. Neither is written to our file storage or to the database, and the conversion cannot be fetched again later. The working copy on the server, with everything the conversion wrote, is deleted as soon as the conversion has ended, also when it fails, runs into the time limit or the request is cancelled.

What is kept#

For billing and to stop abuse, each conversion leaves one entry in the usage history:

The entry shows up in the dashboard like other conversions, without a name. It is kept for 400 days like all usage history, see the privacy policy.

Simple API#

Add ?store=false to POST /v1/convert and send the file as multipart/form-data. The response is the converted file itself with 200, so there is no wait and no polling:

curl "https://api.switchfile.io/v1/convert?store=false" \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY" \
  -F file=@invoice.docx -F to=pdf \
  -o invoice.pdf

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

const form = new FormData();
form.append("file", new Blob([await readFile("invoice.docx")]), "invoice.docx");
form.append("to", "pdf");
const res = await fetch("https://api.switchfile.io/v1/convert?store=false", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SWITCHFILE_API_KEY}` },
  body: form,
});
if (!res.ok) throw new Error(`${res.status} ${(await res.json()).code}`);
await writeFile("invoice.pdf", Buffer.from(await res.arrayBuffer()));

• A conversion with several result files, such as one image per page, comes back as one ZIP file.
• X-Conversion-Id names the entry in the usage history, X-Credits the credits it used.
• X-Notes is set when there are notes on the result, as a JSON array. An incomplete result has X-Incomplete: 1 and names the missing pages in the notes. The first 5 of a day have X-Credits: 0.
• The header Switchfile-Store: false does the same as ?store=false.
• Storage is needed for url, upload_id and from, so this mode takes only an uploaded file.
• A failed conversion comes back as problem JSON with its code.

Jobs#

Send "store": false to POST /sync/v2/jobs. The job has three tasks, one of each: import/base64, convert and export/url. The answer is the finished job, and the export task holds each file as base64 in content instead of a URL:

curl https://api.switchfile.io/sync/v2/jobs \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY" \
  -H "Switchfile-Store: false" \
  -H "Content-Type: application/json" \
  -d "{
    \"store\": false,
    \"tasks\": {
      \"import-1\": {\"operation\": \"import/base64\", \"file\": \"$(base64 < invoice.docx | tr -d '\n')\", \"filename\": \"invoice.docx\"},
      \"convert-1\": {\"operation\": \"convert\", \"input\": \"import-1\", \"output_format\": \"pdf\"},
      \"export-1\": {\"operation\": \"export/url\", \"input\": \"convert-1\"}
    }
  }"

{
  "data": {
    "status": "finished",
    "tasks": [
      {
        "name": "export-1",
        "operation": "export/url",
        "status": "finished",
        "result": { "files": [{ "filename": "invoice.pdf", "size": 48213, "content": "JVBERi0xLjcK..." }] }
      }
    ]
  }
}

With "redirect": true, the response is the file itself, or a ZIP file for several results. The job ID is in X-Job-Id. A failed job comes back as JSON with the failed task, as usual.

Only POST /sync/v2/jobs works without storage: the result has to come back in the same request. Asynchronous jobs under /v2/jobs are rejected with 422, and so are webhooks and any import or export operation other than the ones above.

For the whole account#

Turn it on for every request of your account with PATCH /v1/account:

curl -X PATCH https://api.switchfile.io/v1/account \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"no_store": true}'

From then on every conversion of the account runs without storage: a request to POST /v1/convert or POST /sync/v2/jobs needs no store=false. Requests that would store a file fail with 403 STORAGE_DISABLED, for example uploads, batches, ZIP archives, accessibility checks and task retries. A request with store=true fails with 422. GET /v1/account shows the setting in no_store, and max_file_size then shows the limit of this mode. {"no_store": false} turns it off again.

Conversions and jobs created before you turned it on store nothing more. A task that has not run yet fails with STORAGE_DISABLED, and so does an import/upload task that gets its file afterwards; that file is deleted right away. Files stored before stay until they are deleted as usual. The setting covers requests with the API keys of your account. Conversions on the switchfile.io website run under the website's own key and are kept as the privacy policy describes.

Limits#

A request can take up to 390 seconds from the first byte of the upload to the last byte of the result. The SDKs wait that long in this mode. If you call the API yourself, set your HTTP client's timeout to at least 390 seconds.

What does not work in this mode, and why:

• Webhooks: the response already holds the result, and there is nothing to fetch later.
• Idempotency-Key: a repeated request cannot return a result that was not kept. Send the request again instead.
• X-End-User: visitor quotas of service keys need stored conversions.

Errors#

The other codes are the same as for stored conversions, see Errors.

How the request travels#

Like every request to api.switchfile.io, a request without storage passes through the network of Cloudflare, which ends the encrypted connection and forwards the request to our server in the EU (see the privacy policy). Responses without storage carry Cache-Control: no-store, so they are not cached on the way. On our server, the file and the result are processed in memory while the request runs.