Convert files

​

Convert a file

from doconda import Doconda

doconda = Doconda()  # reads DOCONDA_API_KEY

result = doconda.convert({"url": "https://example.com/contract.pdf"}, "md")
print(result["text"][:60], result["pages"])

import { Doconda } from "@doconda/sdk"

const doconda = new Doconda() // reads DOCONDA_API_KEY

const result = await doconda.convert({ url: "https://example.com/contract.pdf" }, "md")
console.log(result.text?.slice(0, 60), result.pages)

{
  "object": "conversion",
  "id": "doc_01JAB3H8K2M7V6X5T1R0NPQ4ZW",
  "from": "pdf",
  "to": "md",
  "text": "# Lease agreement\n\nThis agreement is made…",
  "output": null,
  "pages": 7,
  "expires_at": null
}

​

What becomes what

​

Read the result

• md, txt, html and csv come back in text, and output is null. Doconda deletes the result as soon as it answers, so GET /convert/{id} returns 404 not_found afterwards.
• docx, pdf, odt, rtf, xlsx and pptx come back in output, and text is null. output.url is a download link valid 5 minutes. The file is deleted 15 minutes after it was made (expires_at); until then, GET /convert/{id} returns a fresh link.

from pathlib import Path
import httpx

result = doconda.convert("notes.md", "docx")
Path("notes.docx").write_bytes(httpx.get(result["output"]["url"]).content)

import { writeFile } from "node:fs/promises"

const result = await doconda.convert("notes.md", "docx")
await writeFile("notes.docx", new Uint8Array(await (await fetch(result.output!.url)).arrayBuffer()))

• Word: headings, lists, tables, pictures and footnotes. Shapes, text boxes and charts don’t go into Markdown, HTML or RTF.
• PowerPoint: one section per slide (separated by ---), the title as ##, bullets with their level, tables, pictures by their alternative text and speaker notes as a quote.
• Excel: one table per visible sheet, with the values the cells show (formulas calculated). To CSV, only the first sheet.
• PDF: headings, paragraphs, lists and tables rebuilt from the page; repeated headers, footers and page numbers are left out.
• Scanned PDFs and pictures: read with OCR.
• To PDF: documents use the same fonts Doconda uses everywhere (Calibri as Carlito, Cambria as Caladea…).

​

Wait for a long conversion

​

Price

• Failed conversions are not charged and don’t count toward the free 1,000.
• Past the free ones with no balance left, the call is rejected with 402 insufficient_balance.
• A conversion doesn’t appear in the documents list and sends no webhooks.
• Conversions count toward the limit of 120 documents per minute per organization; above it, 429 rate_limited.

​

Four ways to pass a file

curl https://api.eu.doconda.com/v1/convert \
  -H "Authorization: Bearer $DOCONDA_API_KEY" \
  -F to=pdf \
  -F file=@report.docx

• Files are limited to 20 MB.
• URLs must point to public addresses; private and local addresses are rejected.
• A file sent by URL, base64 or multipart is deleted 15 minutes after the call.

​

From the SDK

text = doconda.convert("file_01JAB3…", "md")["text"]
url = doconda.convert("https://example.com/notes.md", "docx")["output"]["url"]
pdf = doconda.convert(b"# Notes\n\nFirst point.", "pdf", filename="notes.md")

const { text } = await doconda.convert("file_01JAB3…", "md")
const { output } = await doconda.convert("https://example.com/notes.md", "docx")
const pdf = await doconda.convert(new TextEncoder().encode("# Notes\n\nFirst point."), "pdf", { filename: "notes.md" })

​

Next steps