MarkItDown API

REST API for converting documents and web pages to Markdown, powered by microsoft/markitdown.

Supported Formats

Format	Extensions
PDF	.pdf
Word	.docx
PowerPoint	.pptx
Excel	.xlsx, .xls
HTML	.html, .htm
Text / CSV / JSON / XML	.txt, .csv, .json, .xml
Images	.jpg, .png, .gif, .webp
Audio	.mp3, .wav
URL	any web page

Quick Start

Docker Compose

docker compose up --build

API will be available at http://localhost:8000.
Swagger UI — http://localhost:8000/docs.

---

Endpoints

GET /health

Service health check.

curl http://localhost:8000/health
# {"status":"ok"}

---

POST /convert

Converts a file or URL to Markdown.

Parameters (multipart/form-data, provide one):

Parameter	Type	Description
file	file	File to upload
url	string	URL of a page or document

Response:

{
  "markdown": "# Title\n\nContent...",
  "source": "document.pdf"
}

Examples

# Convert a file
curl -X POST http://localhost:8000/convert \
  -F "[email protected]"

# Convert a URL
curl -X POST http://localhost:8000/convert \
  -F "url=https://example.com"

# Markdown only via jq
curl -s -X POST http://localhost:8000/convert \
  -F "url=https://example.com" | jq -r .markdown

PowerShell:

# File
Invoke-RestMethod -Uri http://localhost:8000/convert `
  -Method POST -Form @{ file = Get-Item "document.pdf" }

# URL
Invoke-RestMethod -Uri http://localhost:8000/convert `
  -Method POST -Form @{ url = "https://example.com" }

---

Development & Tests

Local Setup

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -e "markitdown/packages/markitdown[all]"
pip install fastapi "uvicorn[standard]" python-multipart pytest httpx

Run the API

uvicorn app.main:app --reload

Run Tests

# Unit tests only (no network required)
pytest

# Including integration tests (requires internet)
pytest -m integration

---

Project Structure

markitdown-service/
├── app/
│   └── main.py              # FastAPI application
├── tests/
│   ├── fixtures/            # Test files
│   │   ├── sample.html
│   │   └── sample.txt
│   └── test_api.py          # Tests
├── markitdown/              # microsoft/markitdown source (git submodule)
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── .gitignore
└── README.md

---

License

MIT — see LICENSE.