Knowledge Base

Sending & receiving files

How a file goes in and how the result comes back differs by tool — check each endpoint’s reference. This guide gives you the three input shapes and three output shapes so nothing surprises you.

Sending a file

There are three input conventions across the platform:

Multipart file upload — the default for almost every tool. Send multipart/form-data with a file part plus form fields. Don’t set Content-Type by hand; let your client set the multipart boundary.
Base64 in JSON — used by Compress PDF, which takes application/json with the PDF as a Base64 string in file_data plus a filename.
Remote URL or Base64 — over MCP, tools take file_url (a public URL fetched server-side, up to 25 MB) or file_base64.

Content type is per-endpoint

Don’t assume one shape. Compression is JSON+Base64; nearly everything else is multipart. Each reference page states the exact content type and field names.

Multipart (most tools)

curl -X POST https://api.bytefuse.in/api/v1/conversion/single \
  -H "X-API-Key: dt_live_your_key" \
  -F "file=@report.pdf" \
  -F "target_format=docx"

Base64 JSON (compression)

curl -X POST https://api.bytefuse.in/api/v1/compression/single \
  -H "Content-Type: application/json" \
  -d '{ "file_data": "JVBERi0xLjQK...", "filename": "report.pdf" }'

Receiving a result

Results come back in one of three ways — the reference for each tool tells you which:

A download URL in JSON — compression, conversion, watermarks, image tools, repair, PDF/A, page numbers, and more return { "url": "…" } (or output_url / download_url) pointing at the finished file on R2.
A streamed file — the page tools (rotate, delete, extract, reorder, crop) and bulk certificates return the file bytes directly (the ZIP, for certificates) with a Content-Disposition: attachment header. Read the raw body and save it.
Inline JSON content — OCR text, PDF→Markdown, the AI tools, and the analysis tools return the actual content in the JSON body (text, markdown, data, result) — no file to download.

Download URLs & expiry

When a tool returns a URL, it’s a public link on the storage host. Only Compress PDF returns an expires_at (a 24-hour window). The other URL-returning tools don’t advertise an expiry — treat the link as available but not permanent, and download promptly (or re-run the tool) rather than storing the URL long-term.

Persist the bytes, not the URL

The robust pattern is: call the tool, immediately fetch the returned URL, and store the file bytes in your own storage. Don’t hand the storage URL to end users as a durable link.

PreviousSync & async Next Choosing an engine