Folio

Converting

POST /api/folio/v1/convert

Authenticated with Authorization: Bearer folio_live_….

Sending the document

Two ways in, chosen by Content-Type.

As the request body. One round trip, and what to reach for by default. The filename travels in a header because the body is the document itself.

curl -X POST https://quirelabs.com/api/folio/v1/convert \
  -H "Authorization: Bearer $FOLIO_KEY" \
  -H "x-filename: report.docx" \
  --data-binary @report.docx

?filename=report.docx works too, if a header is awkward.

By key, for anything large. See large documents for the full sequence.

curl -X POST https://quirelabs.com/api/folio/v1/convert \
  -H "Authorization: Bearer $FOLIO_KEY" \
  -H "content-type: application/json" \
  -d '{"key": "uploads/…/contract.pdf"}'

The response

{
  "markdown": "# Quarterly report\n…",
  "format": "pdf",
  "bytes": 91769,
  "durationMs": 936.63,
  "pages": { "total": 3, "text": 2, "ocr": 1, "ocrPages": [2] },
  "usage": { "documents": 1, "ocrPages": 1, "used": 119, "included": 10000 }
}

| Field | Meaning | | --- | --- | | markdown | GitHub-flavored Markdown. Tables, lists, headings and footnotes are preserved. | | format | What the document actually was, detected from its content. | | bytes | Size of the document read. | | durationMs | Conversion time, excluding transfer. | | pages | PDFs only. Absent for every other format. | | usage | What this request added to the meter, and where the period stands. |

pages.ocrPages lists the 1-based page numbers that were scans. It is there so the charge can be checked against the document rather than taken on trust.

Formats

| Family | Extensions | | --- | --- | | Word | .doc .docx .docm | | PowerPoint | .ppt .pptx .pptm .ppsx | | Excel | .xls .xlsx .xlsm .xlsb | | OpenDocument | .odt .ods .odp | | Portable | .pdf .rtf .epub .csv |

Detection reads the content signature first and falls back to the extension. CSV carries no signature, so it is the one format where the filename decides.

Limits

  • 100MB per document.
  • 60 seconds per request. A large scanned PDF is the realistic way to reach it. OCR is the slow part, at roughly a second per scanned page.
  • Documents sent to storage are deleted as soon as they have been converted, and in any case within the hour.