API · FormatKit

What it does and does not do#

Included Text and data formats: CSV, TSV, JSON, JSONL, Markdown, HTML, XML, plain text.

Not included Images, PDF and audio are not part of the API: they need the browser’s decoders and canvas. Use the web pages for those — files never get uploaded.

Fastest call#

curl · macOS / Linux

curl -sS https://www.file2file.net/api/v1/convert \
  -H 'content-type: application/json' \
  -d '{"from":"csv","to":"json","data":"id,name\n1,Alice\n2,Bob\n"}'

This curl runs as-is (the host is this site). On Windows call curl.exe — in PowerShell curl is an alias for Invoke-WebRequest and lines continue with a backtick; the full version is in the Samples tabs below. Change only data inside -d; newlines in JSON are written as \n.

Base URL and auth#

Base URLhttps://www.file2file.net

No token, no signup, no API key. Protection comes from a body size cap, a per-IP burst budget and a method allowlist — see Limits below.

Cross-origin calls are allowed (CORS) and preflight is handled by OPTIONS, so a browser page can fetch this API directly.

Endpoints#

POST /api/v1/convert Convert a piece of text: send from / to / data in the body
GET /api/v1/formats List every supported pair and the limits
GET /api/v1/health Liveness: version and current time

Four endpoints, one job each: convert, capabilities, health, root. Fetch the capabilities once and cache it at start-up.

Supported pairs#

The second format on each row is the value for to.

From	To	Response type	Note
<code>csv</code>	`json`	`application/json`	header row to objects
<code>csv</code>	`tsv`	`text/tab-separated-values`	commas to tabs
<code>csv</code>	`txt`	`text/plain`	flatten the table to plain text
<code>tsv</code>	`csv`	`text/csv`	tabs to commas
<code>tsv</code>	`json`	`application/json`	tab table to objects
<code>json</code>	`csv`	`text/csv`	objects to CSV, union of keys
<code>json</code>	`tsv`	`text/tab-separated-values`	objects to a tab table
<code>json</code>	`txt`	`text/plain`	flatten JSON to plain text
<code>jsonl</code>	`csv`	`text/csv`	one object per line to CSV
<code>md</code>	`html`	`text/html`	Markdown to a complete HTML document
<code>md</code>	`txt`	`text/plain`	drop the markup, keep the prose
<code>html</code>	`txt`	`text/plain`	strip tags, keep text
<code>xml</code>	`txt`	`text/plain`	text content out of XML
<code>txt</code>	`html`	`text/html`	plain text to HTML, line breaks kept

Try it here#

This text is sent to the server for conversion (the file converter never uploads). Use test data only.

From To No request sent yet

Input 0

Output 0

Request parameters#

from, to and data are required; the rest are optional and can also be passed as query parameters (handy for pipes and curl).

Parameter	Where	Type	Required	Notes
<code>from</code>	body	`string`	required	Source format, e.g. csv, markdown, html.
<code>to</code>	body	`string`	required	Target format; must be one of the pairs listed by /api/v1/formats.
<code>data</code>	body	`string`	required	The text to convert (not a file path).
<code>eol</code>	query	`lf \| crlf`	optional	Output line endings: lf or crlf. Defaults to crlf.
<code>delimiter</code>	query	`string`	optional	Delimiter for tabular output (e.g. ; or \t).
<code>bom</code>	query	`1`	optional	Pass 1 to prefix the output with a UTF-8 BOM (for Excel).
<code>format</code>	query	`raw`	optional	Pass raw to receive the converted text directly, without the JSON envelope.

Limits and fair use#

Limit	Value
Max body	256 KB
Max rows	20000
Burst per IP	30 / 60s

What keeps it safe without a token

hard body-size and row-count caps inside the Worker
short-window rate limit per source IP (best effort, inside the Worker)
Cloudflare rate limiting rules, Bot Fight Mode and managed WAF rules
nothing is stored: logs carry only method, path, status and duration

The server keeps no request content; logs hold only method, path, status and timing.

Error codes#

Code	Status	Meaning
bad_request	400	malformed request: from/to/data missing or incompatible
unsupported_pair	400	unsupported pair, see GET /api/v1/formats
bad_json	400	data is not valid JSON
empty_data	400	data is empty
too_large	413	body over 262144 bytes
too_many_rows	413	over 20000 rows
unsupported_media	415	content-type not supported, use application/json or text/*
rate_limited	429	too many requests, slow down and retry
method_not_allowed	405	method not allowed here
not_found	404	no such endpoint
server_error	500	conversion failed on the server

Failure (4xx / 5xx)

Errors always use the same envelope: ok is false, error.code is safe to branch on, error.message is a human-readable English sentence.

Failure (4xx / 5xx)

{
  "ok": false,
  "error": {
    "code": "unsupported_pair",
    "message": "This pair is not supported. See /api/v1/formats for the list."
  }
}

Examples#

curl -sS https://www.file2file.net/api/v1/convert \
  -H 'content-type: application/json' \
  -d '{"from":"csv","to":"json","data":"id,name\n1,Alice\n2,Bob\n"}'

# PowerShell: call curl.exe ("curl" is an alias for Invoke-WebRequest)
# Continue lines with a backtick, and escape each inner double quote with a backslash
curl.exe -sS https://www.file2file.net/api/v1/convert `
  -H "content-type: application/json" `
  -d '{\"from\":\"csv\",\"to\":\"json\",\"data\":\"id,name\n1,Alice\n2,Bob\n\"}'

# CMD: single quotes do not work either - one line, double quotes, escaped quotes
curl.exe -sS https://www.file2file.net/api/v1/convert -H "content-type: application/json" -d "{\"from\":\"csv\",\"to\":\"json\",\"data\":\"id,name\n1,Alice\n2,Bob\n\"}"

import requests

resp = requests.post(
    "https://www.file2file.net/api/v1/convert",
    json={"from": "csv", "to": "json", "data": "id,name\n1,Alice\n2,Bob\n"},
    timeout=15,
)
resp.raise_for_status()
print(resp.json()["data"])   # [{"id": "1", "name": "Alice"}, ...]

import json, urllib.request

payload = json.dumps({
    "from": "md", "to": "html",
    "data": "# Title\n\nBody with **bold**.\n",
}).encode()

req = urllib.request.Request(
    "https://www.file2file.net/api/v1/convert",
    data=payload,
    headers={"content-type": "application/json"},
)
with urllib.request.urlopen(req, timeout=15) as r:
    print(json.load(r)["data"])

const res = await fetch("https://www.file2file.net/api/v1/convert", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ from: "json", to: "csv", data: '[{"a":1,"b":2}]' }),
});
const { data } = await res.json();
console.log(data);

# text/* bodies are accepted too; from/to go in the query string
cat table.csv | curl -sS --data-binary @- \
  "https://www.file2file.net/api/v1/convert?from=csv&to=json"

# CSV in, CSV out with explicit LF endings
curl -sS --data-binary @table.csv \
  "https://www.file2file.net/api/v1/convert?from=csv&to=tsv&eol=lf" -o out.tsv

# Windows PowerShell: the same pipe, but curl.exe (see the curl.exe tab)
Get-Content table.csv -Raw | curl.exe -sS --data-binary @- "https://www.file2file.net/api/v1/convert?from=csv&to=json"

Success (200)

data holds the converted text. Add ?format=raw to get the raw text instead of the JSON envelope. bytes is the size of data; quota.remaining is your own remaining budget for the current minute - the number in the sample is just what it happened to be.

Success (200)

{
  "ok": true,
  "api": "v1",
  "from": "csv",
  "to": "json",
  "mime": "application/json",
  "bytes": 89,
  "data": "[\n  {\n    \"id\": \"1\",\n    \"name\": \"Alice\"\n  },\n  {\n    \"id\": \"2\",\n    \"name\": \"Bob\"\n  }\n]\n",
  "quota": { "remaining": 49, "windowMs": 60000 }
}

Envelope fields

Parameter	Notes
<code>ok</code>	true on success, false on failure (details live in error).
<code>data</code>	The converted text.
<code>mime</code>	MIME type of the result.
<code>bytes</code>	Size of the result in UTF-8 bytes.
<code>quota</code>	Burst budget left for your IP in the current window.
<code>error.code</code>	Machine-readable error code; see the table above.
<code>error.message</code>	One English sentence for humans and logs.

Use the API

What it does and does not do#

Fastest call#

Base URL and auth#

Endpoints#

Supported pairs#

Try it here#

Request parameters#

Limits and fair use#

What keeps it safe without a token

Error codes#

Failure (4xx / 5xx)

Examples#

Success (200)

Envelope fields