This browser-session API powers the Mitdown web client. Stateful calls must come from https://mitdown.ca, send the session cookie, and include an Origin or Referer header; other browser origins are rejected. It is not a token-authenticated public integration API. For interactive use, try the free web converter.

ERRORS Error Contract All API failures

Every non-successful API response is JSON with error.code, error.message, and error.retryable. Validation responses may add error.details, an array of field-level errors. Job failures use this same object in their terminal error field.

{
  "error": {
    "code": "validation.invalid_settings",
    "message": "Invalid conversion settings",
    "details": [{"field": "do_ocr", "code": "invalid_choice"}],
    "retryable": false
  }
}

CONFIG Conversion Settings Optional settings

Include any of these optional fields in multipart form data requests to control backend parsing behavior. Invalid values return 400; the server never silently replaces them with defaults.

Field	Type	Default	Valid Values	Description
`do_ocr`	boolean	`true`	`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	`off`	`off`, `fast`, `accurate`	Table extraction mode (Docling only). `accurate` uses a slower ML-based pipeline.
`images_scale`	number	`0.5`	`0.5`, `1`, `2`	Resolution scale factor for images embedded in the output.
`heading_style`	string	`ATX`	`ATX`, `SETEXT`	Markdown heading style (MarkItDown only). `ATX` uses `#` prefixes; `SETEXT` uses underlines.
`split_level`	integer	`2`	`1`, `2`, `3`	Heading depth used when `split_headers=true`.

API Endpoint Reference

POST /api/convert Convert single document

Convert a single file asynchronously. The request must be sent as multipart/form-data. A new conversion returns 202 Accepted and a job identifier; poll /api/jobs/<job_id> until it reaches a terminal status.

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.
`Idempotency-Key`	header	No	Unique client-generated key (1 to 128 characters). Reusing it for the same submission returns the original queued job; reusing it for different input returns `409`.
Conversion Settings	N/A	No	See the Conversion Settings section above.

cURL Request

# Keep this cookie jar for the subsequent job and download requests.
curl -c mitdown.cookies \
  -H "Origin: https://mitdown.ca" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -F "file=@report.pdf" \
  -F "split_headers=false" \
  https://mitdown.ca/api/convert

Accepted Response (HTTP 202)

{
  "job_id": "a1b2c3d4...",
  "status": "queued"
}

Poll: GET /api/jobs/a1b2c3d4... with the same cookie. A duplicate completed submission may instead return 200 with status: "finished" and the completed result.

POST /api/convert/batch Convert multiple documents

Convert multiple files in one asynchronous request for any backend (Markit, MarkItDown, or Docling). Send multipart/form-data and poll the returned job. When at least one file succeeds, the finished payload includes download_all_url pointing at a zip of results.

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.
`Idempotency-Key`	header	No	Unique client-generated key; see the single conversion endpoint for replay semantics.
Conversion Settings	N/A	No	See the Conversion Settings section above.

cURL Request

curl -c mitdown.cookies \
  -H "Origin: https://mitdown.ca" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001" \
  -F "files[]=@doc1.pdf" \
  -F "files[]=@doc2.docx" \
  -F "split_headers=false" \
  https://mitdown.ca/api/convert/batch

Accepted Response (HTTP 202)

{
  "job_id": "e5f6g7h8...",
  "status": "queued"
}

GET /api/convert/current-backend Get active backend

Returns the conversion backend active for this session, the formats it supports, and presentation metadata in brand. With no prior selection, it reports the default markit backend without creating or changing session state.

cURL Request

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

JSON Response

{
  "current_backend": "markit",
  "supported_formats": ["pdf", "powerpoint", "word", "excel", "html", "json", "xml", "image", "csv", "audio", "zip", "epub", "yaml"],
  "brand": { "name": "Markit", "description": "..." }
}

POST /api/convert/switch-backend Switch active backend

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

Parameters

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

cURL Request

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

JSON Response

{
  "message": "Successfully switched to docling backend",
  "current_backend": "docling",
  "supported_formats": ["pdf", "powerpoint", "word", "excel", "csv", "html", "json", "xml", "image", "epub", "zip"],
  "brand": { "name": "Docling", "description": "..." }
}

GET /api/jobs/<job_id> Poll an asynchronous conversion

Poll a conversion submitted by this browser session. Keep the same session cookie used for submission. Jobs expire after the server retention period; unknown and foreign jobs both return 404.

Non-terminal responses have status: "queued" with position, progress, and status_text, or status: "running" with progress and status_text. Terminal values are "finished" (the conversion result), "failed" (with error), and "canceled" (job stopped by the owning session).

cURL Request

curl -b mitdown.cookies \
  https://mitdown.ca/api/jobs/a1b2c3d4...

Finished Response (HTTP 200)

{
  "status": "finished",
  "conversion_status": "SUCCESS",
  "filename": "report.md",
  "download_url": "/api/download/...",
  "is_split": false,
  "markdown": "# Report\n\nContent here…"
}

Failed Response (HTTP 200)

{
  "status": "failed",
  "error": {"code": "conversion.failed", "message": "Conversion failed. Please try again.", "retryable": true}
}

DELETE /api/jobs/<job_id> Cancel an asynchronous conversion

Cancel a job owned by this browser session. Queued jobs are removed and their spool data deleted. Jobs already running are stopped on a best-effort basis; the worker may finish the current unit of work. Unknown and foreign jobs both return 404.

Idempotent: canceling an already finished or failed job returns that terminal status without error.

cURL Request

curl -X DELETE -b mitdown.cookies \
  https://mitdown.ca/api/jobs/a1b2c3d4...

Canceled Response (HTTP 200)

{
  "status": "canceled"
}

GET /api/download/<id>/<filename> Download single conversion

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

Path Parameters

Parameter	Description
`id`	An opaque conversion identifier returned in `download_url`.
`filename`	The filename of the generated document.

Query Parameters

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

cURL Request

curl -b mitdown.cookies -OJ "https://mitdown.ca/api/download/a1b2c3d4/report.md?is_split=false"

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

GET /api/download/batch/<id>/<filename> Download batch converted file

Download a single converted file from a batch conversion result.

Path Parameters

Parameter	Description
`id`	The `batch_id` returned by the batch conversion route.
`filename`	The filename of the individual converted file.

cURL Request

curl -b mitdown.cookies -OJ "https://mitdown.ca/api/download/batch/e5f6g7h8/doc1.md"

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

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

Path Parameters

Parameter	Description
`id`	The `batch_id` returned by the batch conversion route.

cURL Request

curl -b mitdown.cookies -OJ "https://mitdown.ca/api/download/batch/e5f6g7h8/all"

GET /api/history Get conversion history

Retrieve up to the latest 50 conversion-history entries for the current session. When truncated is true, older entries were discarded and cannot be retrieved.

cURL Request

curl -b mitdown.cookies https://mitdown.ca/api/history

JSON Response

{
  "history": [
    {
      "backend": "markitdown",
      "conversion_id": "a1b2c3d4",
      "download_url": "/api/download/a1b2c3d4/report.md?is_split=false",
      "filename": "report.md",
      "is_batch": false,
      "is_split": false,
      "timestamp": 1716499800000
    }
  ],
  "limit": 50,
  "truncated": false
}

DELETE /api/history Clear conversion history

Clear all conversion history for the current session.

cURL Request

curl -b mitdown.cookies \
  -X DELETE https://mitdown.ca/api/history \
  -H "Origin: https://mitdown.ca"

JSON Response

{
  "message": "History cleared"
}

POST /api/contact Submit a contact message

Submit a JSON contact message from the Mitdown browser session. Required string fields are name, email, subject, and message. Send the client timestamp _ts in milliseconds; submissions less than three seconds old are rejected. Leave the optional honeypot field website empty.

Length limits: name 100, email 254, subject 200, and message 5,000 characters.

cURL Request

TS=$(date +%s000)
curl -X POST https://mitdown.ca/api/contact \
  -H "Origin: https://mitdown.ca" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"Ada\",\"email\":\"ada@example.com\",\"subject\":\"Hello\",\"message\":\"Question\",\"_ts\":$TS}"

JSON Response

{
  "success": true,
  "message": "Thank you for your message. We will get back to you soon!"
}