REST API Reference

Conversion Settings

The following optional fields may be included in any multipart conversion request to control conversion behaviour.

Field	Type	Default	Valid Values	Description
do_ocr	boolean	false	true, false	Run OCR on scanned pages or images inside the document.
force_ocr	boolean	false	true, false	Force OCR even when the document contains selectable text.
table_mode	string	fast	fast, accurate	Table extraction mode. accurate uses a slower ML-based pipeline.
images_scale	number	2	Positive number (e.g. 1, 2, 3)	Resolution scale factor for images embedded in the output.
heading_style	string	atx	atx, setext	Markdown heading style. atx uses # prefixes; setext uses underlines.

POST /api/convert

Convert a single file to Markdown. The request must be multipart/form-data.

Parameters

Field	Type	Required	Description
file	file	Yes	The document to convert (PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, XML, …).
split_headers	boolean	No	When true, splits the output on top-level headings and returns a ZIP archive instead of a single .md file.
Conversion Settings	—	No	See the Conversion Settings section above.

Example

curl -X POST https://mitdown.ca/api/convert \
  -F "file=@report.pdf" \
  -F "split_headers=false"

Response

{
  "success": true,
  "conversion_id": "a1b2c3d4",
  "filename": "report.md",
  "download_url": "/api/download/a1b2c3d4/report.md",
  "is_split": false,
  "markdown": "# Report\n\nContent here…"
}

POST /api/convert/batch

Convert multiple files in a single request. The request must be multipart/form-data.

Parameters

Field	Type	Required	Description
files[]	file[]	Yes	One or more files to convert. Repeat the field for each file.
split_headers	boolean	No	When true, each converted file is split on top-level headings.
Conversion Settings	—	No	See the Conversion Settings section above.

Example

curl -X POST https://mitdown.ca/api/convert/batch \
  -F "files[]=@doc1.pdf" \
  -F "files[]=@doc2.docx" \
  -F "split_headers=false"

Response

{
  "success": true,
  "batch_id": "e5f6g7h8",
  "results": [
    {
      "filename": "doc1.md",
      "download_url": "/api/download/batch/e5f6g7h8/doc1.md",
      "success": true
    },
    {
      "filename": "doc2.md",
      "download_url": "/api/download/batch/e5f6g7h8/doc2.md",
      "success": true
    }
  ],
  "all_download_url": "/api/download/batch/e5f6g7h8/all"
}

GET /api/convert/current-backend

Returns the conversion backend currently active for this session.

Example

curl https://mitdown.ca/api/convert/current-backend

Response

{
  "backend": "markitdown"
}

POST /api/convert/switch-backend

Switch the conversion backend for the current session. Send a JSON body.

Parameters

Field	Type	Required	Valid Values	Description
backend	string	Yes	markitdown, docling	The backend to activate for subsequent conversions.

Example

curl -X POST https://mitdown.ca/api/convert/switch-backend \
  -H "Content-Type: application/json" \
  -d '{"backend": "docling"}'

Response

{
  "success": true,
  "backend": "docling"
}

GET /api/download/<id>/<filename>

Download a previously converted file by its conversion ID and filename.

Path Parameters

Parameter	Description
id	The conversion_id returned by POST /api/convert.
filename	The filename returned in the conversion response.

Query Parameters

Parameter	Type	Description
is_split	boolean	Set to true when downloading a split ZIP archive.

Example

curl -O "https://mitdown.ca/api/download/a1b2c3d4/report.md"

# For split output:
curl -O "https://mitdown.ca/api/download/a1b2c3d4/report.zip?is_split=true"

GET /api/download/batch/<id>/<filename>

Download a single converted file from a batch conversion result.

Path Parameters

Parameter	Description
id	The batch_id returned by POST /api/convert/batch.
filename	The filename of the individual converted file within the batch.

Example

curl -O "https://mitdown.ca/api/download/batch/e5f6g7h8/doc1.md"

GET /api/download/batch/<id>/all

Download all files from a batch conversion as a single ZIP archive.

Path Parameters

Parameter	Description
id	The batch_id returned by POST /api/convert/batch.

Example

curl -O "https://mitdown.ca/api/download/batch/e5f6g7h8/all"

GET /api/history

Retrieve the conversion history for the current session.

Example

curl https://mitdown.ca/api/history

Response

{
  "history": [
    {
      "conversion_id": "a1b2c3d4",
      "filename": "report.md",
      "original_filename": "report.pdf",
      "converted_at": "2026-03-22T14:30:00Z",
      "download_url": "/api/download/a1b2c3d4/report.md",
      "is_split": false,
      "backend": "markitdown"
    }
  ]
}

DELETE /api/history

Clear all conversion history for the current session.

Example

curl -X DELETE https://mitdown.ca/api/history

Response

{
  "success": true,
  "message": "History cleared."
}