Convert a file

Send the file as multipart/form-data in the field file, or JSON with exactly one of url, upload_id and from. Answers with 202 right away. With ?wait=N (up to 30) the request waits up to N seconds and answers 200 if the conversion is done by then. With Accept: application/octet-stream and wait, a finished conversion returns the file itself (up to 50 MB, otherwise 303 to the download URL). ?dry_run=1 only returns the credits and the price. Supports Idempotency-Key.

POSThttps://api.switchfile.io/v1/convert

Needs an API key: Authorization: Bearer YOUR_API_KEY. See Authentication.

Example

Request

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

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

const form = new FormData();
form.append("file", new Blob([await readFile("report.docx")]), "report.docx");
form.append("to", "pdf");

const res = await fetch("https://api.switchfile.io/v1/convert?wait=30", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SWITCHFILE_API_KEY}`,
  },
  body: form,
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
console.log(await res.json());

<?php
$ch = curl_init('https://api.switchfile.io/v1/convert?wait=30');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('report.docx'),
        'to' => 'pdf',
    ],
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SWITCHFILE_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new RuntimeException("HTTP $status: $response");
}
print_r(json_decode($response, true));

import os
import requests

res = requests.post(
    "https://api.switchfile.io/v1/convert?wait=30",
    headers={"Authorization": f"Bearer {os.environ['SWITCHFILE_API_KEY']}"},
    files={"file": open("report.docx", "rb")},
    data={"to": "pdf"},
)
res.raise_for_status()
print(res.json())

Parameters

Query parameters

waitnumber
Wait up to this many seconds for the result (at most 30)
0 to 300 · example: 30
dry_runstring
1 or true: only return the credits and the price. Nothing is created or charged
one of "1", "true", "0", "false"

Headers

Idempotency-Keystring
1 to 255 visible ASCII characters, for example a UUID. Send the request again with the same key after a timeout: nothing is created twice. Kept for 24 hours.
example: 6f1c2b8e-1d8e-4c55-9f0e-3f3f0b0a8f21
Acceptstring
application/octet-stream together with wait: a finished conversion returns the file itself instead of JSON.
example: application/octet-stream
X-End-Userstring
Service keys only: an ID for the visitor you act for (1 to 128 characters: letters, digits and . _ : @ -). Quotas and rate limits then count per visitor.
X-End-User-Ipstring
Required with X-End-User: the IP address of the visitor.

Request body

As application/json

filenamestring
File name of the input
1 to 255 characters
fromstring (uuid)
ID of an earlier conversion. Its input is converted again, without a new upload
input_formatstring
Input format, if the file name does not show it
1 to 20 characters
optionsmap of string | number | boolean | null
Settings for the conversion, for example { "quality": 80 }. null and an empty string count as not set. See the options per target format in the docs
at most 50 entries · keys match ^[a-z][a-z0-9_]{0,63}$
presetstring
ID or name of a preset from the dashboard. It sets the target format and the options. Values in options override single settings of the preset. A preset with an input format only takes files of that format.
1 to 100 characters
tostring
Target format, for example mp4. Required without preset. With preset it is optional and must match the preset
1 to 20 characters
upload_idstring (uuid)
ID of a file sent through POST /v1/uploads
urlstring
Download the input from this public http or https URL
1 to 4096 characters
webhook_urlstring
at most 4096 characters · matches ^https?://

As multipart/form-data

filefilerequired
The file to convert, up to 100 MB
filenamestring
File name of the input
input_formatstring
Input format, if the file name does not show it
optionsstring
Settings as a JSON object in text form, for example {"quality":80}
presetstring
ID or name of a preset
tostring
Target format, for example pdf. Required without preset
webhook_urlstring
Send conversion.finished or conversion.failed to this URL

Responses

200Done within wait, or the estimate for dry_run

200 application/json

{
  "id": "0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10",
  "object": "conversion",
  "status": "finished",
  "progress": 100,
  "input": {
    "filename": "report.docx",
    "format": "docx",
    "size": 48213
  },
  "to": "pdf",
  "options": {},
  "result": {
    "files": [
      {
        "filename": "report.pdf",
        "size": 61544,
        "url": "https://api.switchfile.io/files/2a6f8e1c-4b3d-4e7a-9c5f-8d1b0e2a4c67/report.pdf?expires=1762538401&signature=3f9c2a7d41e8b6c05d1f9e2a7b4c8d3e6f0a1b2c3d4e5f60718293a4b5c6d7e8"
      }
    ]
  },
  "download_url": "https://api.switchfile.io/files/2a6f8e1c-4b3d-4e7a-9c5f-8d1b0e2a4c67/report.pdf?expires=1762538401&signature=3f9c2a7d41e8b6c05d1f9e2a7b4c8d3e6f0a1b2c3d4e5f60718293a4b5c6d7e8",
  "error": null,
  "credits": 2,
  "batch_id": null,
  "created_at": "2026-11-06T18:00:00+00:00",
  "finished_at": "2026-11-06T18:00:02+00:00",
  "expires_at": "2026-11-07T18:00:02+00:00",
  "links": {
    "self": "https://api.switchfile.io/v1/conversions/0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10"
  }
}

202Created, still running. Poll links.self or wait for the webhook
batch_idstring (uuid) | nullrequired
created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
creditsstring (integer) | integerrequired
Credits used, set once the conversion is done
download_urlstring | nullrequired
Signed URL of the first result file
errorobject | nullrequired
error.codestringrequired
error.messagestringrequired
expires_atstring | nullrequired
Input and result are deleted at this time
finished_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
idstring (uuid)required
inputobjectrequired
input.filenamestring | nullrequired
input.formatstring | nullrequired
input.sizestring (integer) | integerrequired
linksobjectrequired
links.selfstringrequired
objectstringrequired
one of "conversion"
optionsmap of anyrequired
keys match ^(.*)$
progressstring (integer) | integerrequired
Progress in percent
0 to 100
resultobject | nullrequired
result.filesConversionFile[]required
result.files[].filenamestringrequired
result.files[].sizestring (integer) | integerrequired
result.files[].urlstringrequired
Signed download URL, works without an API key until expires_at
statusstringrequired
one of "queued", "processing", "finished", "failed"
tostringrequired
202 application/json
```
{
  "id": "0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10",
  "object": "conversion",
  "status": "queued",
  "progress": 0,
  "input": {
    "filename": "report.docx",
    "format": "docx",
    "size": 48213
  },
  "to": "pdf",
  "options": {},
  "result": null,
  "download_url": null,
  "error": null,
  "credits": null,
  "batch_id": null,
  "created_at": "2026-11-06T18:00:00+00:00",
  "finished_at": null,
  "expires_at": null,
  "links": {
    "self": "https://api.switchfile.io/v1/conversions/0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10"
  }
}
```
303Done, the file is larger than 50 MB. The Location header holds the download URL

401The API key is missing or not validUNAUTHENTICATED

401 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-unauthenticated",
  "title": "Unauthenticated",
  "status": 401,
  "code": "UNAUTHENTICATED",
  "detail": "Missing or invalid API key."
}

402Today's free quota is used up and there are not enough creditsCREDITS_EXCEEDED

402 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-credits-exceeded",
  "title": "Credits exceeded",
  "status": 402,
  "code": "CREDITS_EXCEEDED",
  "detail": "Today's free quota is used up and there are not enough credits left."
}

403X-End-User was sent with a key that is not a service keyEND_USER_NOT_ALLOWED

403 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-end-user-not-allowed",
  "title": "End user not allowed",
  "status": 403,
  "code": "END_USER_NOT_ALLOWED",
  "detail": "The X-End-User header is only allowed with a service key."
}

404upload_id, from or preset was not foundNOT_FOUND

404 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-not-found",
  "title": "Not found",
  "status": 404,
  "code": "NOT_FOUND",
  "detail": "Upload not found."
}

409UPLOAD_INCOMPLETE, INPUT_NOT_AVAILABLE or IDEMPOTENCY_KEY_IN_USEUPLOAD_INCOMPLETE

409 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-upload-incomplete",
  "title": "Upload incomplete",
  "status": 409,
  "code": "UPLOAD_INCOMPLETE",
  "detail": "Nothing has been uploaded for this upload_id yet."
}

411The request has a body but no Content-Length headerLENGTH_REQUIRED

411 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-length-required",
  "title": "Length required",
  "status": 411,
  "code": "LENGTH_REQUIRED",
  "detail": "A Content-Length header is required for this request."
}

413The request or the file is too largeFILE_TOO_LARGE

413 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-file-too-large",
  "title": "File too large",
  "status": 413,
  "code": "FILE_TOO_LARGE",
  "detail": "The file is larger than the allowed maximum."
}

415Send JSON or multipart/form-dataUNSUPPORTED_MEDIA_TYPE

415 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-unsupported-media-type",
  "title": "Unsupported media type",
  "status": 415,
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "detail": "Send JSON or multipart/form-data."
}

422Invalid data, an unsupported pair, a bad URL or an unknown presetUNSUPPORTED_PAIR

422 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-unsupported-pair",
  "title": "Unsupported pair",
  "status": 422,
  "code": "UNSUPPORTED_PAIR",
  "detail": "Converting txt to mp4 is not supported."
}

429Too many requests or a daily quota is used up. See Retry-AfterRATE_LIMIT_EXCEEDED

429 application/problem+json

{
  "type": "https://switchfile.io/docs/api/v1#errors-rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "RATE_LIMIT_EXCEEDED",
  "detail": "Too many requests. Try again in 12 seconds."
}

Error bodies and codes are explained in Errors.