API Documentation

API keys

The recommended way to authenticate server-side conversions. Keys start with fc_ and are sent as a Bearer token:

Authorization: Bearer fc_ab12cd34ef56...

• Creating API keys requires a paid plan (Starter, Pro, or Scale).
• The full key is shown only once at creation; it is stored as a one-way hash.
• Revoking a key immediately invalidates it.
• Keys are scoped to your account and cannot be used to access other accounts' data.
• Requests authenticated with an API key are subject to your plan's rate limits, concurrent job limit, and credit costs — identical to using the web app.

JWT access tokens

Registering or logging in returns an accessToken and a refreshToken. Send the access token as a Bearer token on every authenticated request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

• Get a token pair via POST /auth/login with your email and password (or register via POST /auth/register).
• Access tokens expire after 15 minutes.
• When the access token expires (HTTP 401), exchange the refresh token via POST /auth/refresh for a new pair.
• Refresh tokens are single-use, expire after 7 days, and are revoked on logout.

Which endpoints need what

• Public: /converter/formats, guest quota, and auth routes.
• Either JWT or API key: conversion endpoints (guests may omit auth entirely), and file downloads.
• JWT required: conversion history, stats, and API key management.

Success envelope

{
  "success": true,
  "message": "Conversion completed",
  "data": { ... }
}

Paginated endpoints add a meta object with page, limit, total, and totalPages.

Error envelope

{
  "success": false,
  "message": "File size exceeds the 10MB limit",
  "error": "FILE_TOO_LARGE",
  "details": { ... }
}

Every error returns a machine-readable error code. See the Response Codes reference for the full list. When a request is rate-limited, the response includes a Retry-After header (in seconds).

Each conversion has its own endpoint (POST /converter/:slug) so it can accept conversion-specific options alongside the file — for example header and footer text on an HTML-to-PDF job. Upload a single file plus any option fields; every option is optional and defaults when omitted.

curl -X POST https://api.fileswitch.co/api/v1/converter/html-to-pdf \
  -H "Authorization: Bearer fc_YOUR_API_KEY" \
  -F "file=@input.html" \
  -F "pageSize=A4" \
  -F "printBackground=true" \
  -F "marginTop=20px" \
  -F "marginRight=20px" \
  -F "marginBottom=20px" \
  -F "marginLeft=20px"

Endpoints

Conversion endpoints & schemas

One endpoint per conversion. Click through to the endpoint details for the input option schema and a request example. Every endpoint returns the same Conversion response schema.

Downloading the output

The downloadUrl is relative to the API host. Prepend https://api.fileswitch.co to download the file with the same API key (or the owning account's JWT). Files are retained temporarily and auto-deleted, so download outputs promptly:

curl https://api.fileswitch.co/api/v1/converter/download/conversions%2Fb10a5f2e-8c1e-4b3a-9c1d-2e3f4a5b6c7d%2Foutput.pdf \
  -H "Authorization: Bearer fc_YOUR_API_KEY" \
  --output document.pdf

Plans

The effective upload limit is the lower of your plan's max file size and the converter's own limit (currently 25 MB for every supported conversion). Guests are capped at 5 MB.

Rate limiting

• A global rate limit applies to all requests: 100 requests per 15-minute window per IP.
• The conversion endpoint uses a stricter, per-account limiter: your plan's rateLimitRPS sustained over a rolling window.
• Guests get 1 conversion request per 10-second window plus a daily quota.
• Excess traffic returns HTTP 429 with Retry-After.

Guest quota

Without signing in you can convert up to 2 files per day (per IP), each up to 5 MB. The GET /converter/guest/quota endpoint reports how many conversions remain.

Credit costs

Conversions consume credits from your account. The base cost depends on the conversion type — heavy browser-based jobs cost more:

File size adds a multiplier: files ≤ 25 MB cost 1×, files 25–100 MB cost 2×, and files over 100 MB cost 3×. Total cost = base cost × multiplier. Insufficient credits returns HTTP 402. Failed conversions are automatically refunded.

Using the schema

• Open the spec in Swagger Editor for an interactive, browsable reference.
• Import the URL into Postman (File → Import → Link) to generate a collection with every endpoint preconfigured.
• Import into Insomnia (Create → Import → URL) the same way.
• Generate typed clients with openapi-generator or openapi-typescript from the same URL.

Create a key

curl -X POST https://api.fileswitch.co/api/v1/integrations/api-keys \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-server", "expiresInDays": 90}'

Response (201) — the full key is shown exactly once:

{
  "success": true,
  "data": {
    "id": "c47afec6-083c-4228-a108-2271ce598dff",
    "name": "ci-server",
    "keyPrefix": "fc_ab12cd34",
    "lastFour": "5678",
    "lastUsedAt": null,
    "expiresAt": "2026-10-29T13:00:00.000Z",
    "revokedAt": null,
    "createdAt": "2026-07-31T13:00:00.000Z",
    "fullKey": "fc_ab12cd34..."
  }
}

• name is required (1–100 characters). expiresInDays is optional (1–365); omit it for a non-expiring key.
• Returns HTTP 403 with code API_KEYS_REQUIRE_PAID_PLAN on a free plan.
• Returns HTTP 403 with code API_KEY_LIMIT_REACHED when the plan allowance is exhausted.

Endpoints

Keys are scoped to the authenticated user; attempting to revoke another user's key returns 404.

Handling errors & rate limits

import time, requests

headers = {"Authorization": "Bearer fc_YOUR_API_KEY"}

for attempt in range(3):
    res = requests.post(
        "https://api.fileswitch.co/api/v1/converter/json-to-csv",
        headers=headers,
        files={"file": open("data.json", "rb")},
        data={"delimiter": ";"},
    )
    if res.status_code == 429:
        retry_after = int(res.headers.get("Retry-After", 5))
        time.sleep(retry_after)
        continue
    res.raise_for_status()
    break

# 402 -> insufficient credits, 413 -> file too large, 422 -> unsupported input for this endpoint