Getting started

Quickstart

Convert your first file with the switchfile API in two minutes, with cURL or Node.js.

1. Get an API key#

Create a free account and open API keys in the dashboard. Create a key and copy it, it is shown only once. Put it in an environment variable, so it stays out of your code:

Shell

export SWITCHFILE_API_KEY="sf_live_..."

A sandbox key (sf_test_...) works the same way and never uses credits. It is a good start for this guide.

2. Convert a file#

Send a file and the target format. wait=30 keeps the request open for up to 30 seconds, so a short conversion comes back in the same response.

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,
});
const conversion = await res.json();
if (!res.ok) throw new Error(`${conversion.code}: ${conversion.detail}`);
console.log(conversion.status, conversion.download_url);

<?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,
]);
$conversion = json_decode(curl_exec($ch), true);
echo $conversion['status'], ' ', $conversion['download_url'], PHP_EOL;

import os
import requests

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

The answer is the conversion. When status is finished, download_url points to the PDF:

JSON

{
  "id": "0b8a7c1e-5d0f-4a51-9f39-2f7f4c1d9a10",
  "object": "conversion",
  "status": "finished",
  "progress": 100,
  "input": { "filename": "report.docx", "format": "docx", "size": 48213 },
  "to": "pdf",
  "download_url": "https://api.switchfile.io/files/2a6f8e1c-.../report.pdf?expires=...&signature=...",
  "credits": 2,
  "expires_at": "2026-11-07T18:00:02+00:00"
}

The download URL is signed and works without an API key until expires_at, 24 hours after the conversion.

3. Get the file itself#

Add Accept: application/octet-stream and the same request returns the converted file instead of JSON:

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

import { readFile, writeFile } 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}`, Accept: "application/octet-stream" },
  body: form,
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
if (res.headers.get("content-type")?.startsWith("application/json")) {
  console.log("still running:", (await res.json()).links.self);
} else {
  await writeFile("report.pdf", Buffer.from(await res.arrayBuffer()));
}

If the conversion takes longer than wait, you get 202 with the conversion as JSON. Ask for it again with GET /v1/conversions/{id} or let a webhook tell you when it is done.

4. Pick the target and options#

Every target format has its own options, for example quality for JPG or crf for MP4:

Shell

curl "https://api.switchfile.io/v1/convert?wait=30" \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY" \
  -F [email protected] \
  -F to=jpg \
  -F 'options={"quality": 80, "width": 1600}'

Formats and options lists every target with its options, and GET /v1/formats returns all supported pairs as JSON.

Next steps#

Simple API: async conversions, batches, ZIP files and the cost of a conversion before you start it
Uploads: files larger than 100 MB
Jobs and tasks: the CloudConvert-compatible API

AuthenticationSend your switchfile API key as a bearer token. Live keys, sandbox keys, service keys and the endpoints that need no key.Simple APIConvert a file with one request to the switchfile simple API (v1). Synchronous and asynchronous requests, the conversion object, batches, ZIP files and cost estimates.