Web app and API

Markdrop Web is a converter you host yourself. It has a web page for converting files, web pages and YouTube links, and a REST API that scripts, the browser extension and the Telegram bot can call. New to APIs? Read What is an API? first.

Run it

Markdrop Web runs from the source code. Get it first:

git clone https://github.com/Dhiva-Labs/markdrop.git
cd markdrop/04-web-app

With Python

The project's own instructions use uv to create the Python environment:

cd backend
uv venv .venv && uv pip install -p .venv/bin/python -r requirements.txt
.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8460 --reload

Open http://127.0.0.1:8460.

With Docker

docker build -t md-converter .
docker run -p 8000:8000 -e MD_API_KEY=changeme md-converter

Open http://localhost:8000. Replace changeme with a key of your own; see Security.

Use the web page

The page has three tabs:

Tab	What to do
Upload file	Drop a file on the box, or click to choose one.
Web page / file URL	Paste the address of a page, or a direct link to a .pdf, .docx or other file, and select Convert. Wikipedia pages and RSS feeds get special handling.
YouTube	Paste a video link and select Get transcript. You get the title, channel, description and full transcript.

The result appears below, with Copy and Download .md buttons. The supported formats link at the bottom lists what the server can convert.

API endpoints

Method	Path	Body
POST	/api/convert/file	Multipart form with a file field. Optional extension, mimetype and charset fields help with unusual files.
POST	/api/convert/url	JSON {"url": "..."}
POST	/api/convert/youtube	JSON {"url": "..."}
GET	/api/formats	None. Lists the formats the server supports.
GET	/api/health	None.

Convert a file

curl -F "file=@report.docx" http://127.0.0.1:8460/api/convert/file

Convert a web page

curl -X POST http://127.0.0.1:8460/api/convert/url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://en.wikipedia.org/wiki/Markdown"}'

Get a YouTube transcript

curl -X POST http://127.0.0.1:8460/api/convert/youtube \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID"}'

The response

A successful conversion returns:

{
  "ok": true,
  "title": "Markdown - Wikipedia",
  "markdown": "---\ntitle: Markdown - Wikipedia\nsource: https://en.wikipedia.org/wiki/Markdown\n...",
  "source": "https://en.wikipedia.org/wiki/Markdown",
  "warnings": []
}

The markdown field starts with the usual front-matter. See JSON basics if this format is new to you.

Errors

Status	Meaning
400	Bad input: an empty upload, a link that is not allowed, or a link that is not a YouTube watch or Shorts address.
401	The server requires an API key and the X-API-Key header is missing or wrong.
413	The file or download is larger than the limit, 50 MB by default.
415	No converter can handle this type of input.
422	The conversion failed. The error field says why.
429	Too many requests from your address. Wait and try again.
502	The server could not fetch the URL.
504	The conversion took longer than the time limit.

Configuration

Set these environment variables before starting the server.

Variable	Default	What it does
MD_API_KEY	Empty (no key needed)	When set, every request must send this value in the X-API-Key header.
MD_MAX_UPLOAD_BYTES	50 MB	The largest file you can upload.
MD_MAX_DOWNLOAD_BYTES	50 MB	The largest file the server downloads from a URL.
MD_CONVERT_TIMEOUT	60 seconds	The time limit for one conversion.
MD_WORKERS	2	How many conversions can run at the same time.
MD_RATE_PER_MINUTE	30	Requests allowed per minute from one address.
MD_RATE_BURST	10	Requests allowed in a quick burst from one address.
MD_CORS_ORIGINS	*	Which websites may call the API from a browser, comma-separated.
MD_FETCH_TIMEOUT	30 seconds	The time limit for downloading a URL.
MD_ALLOW_PRIVATE_URLS	Off	Allows URLs on private networks. For development only.

With an API key set, send it like this:

curl -H "X-API-Key: your-key" -F "file=@report.docx" http://127.0.0.1:8460/api/convert/file

Security

• Set MD_API_KEY whenever the server can be reached by other people. Without it, anyone who can reach the server can use it.
• Private addresses are blocked. The URL endpoint refuses links to private and local network addresses, and checks every redirect, so the server cannot be used to reach machines on your internal network. Leave MD_ALLOW_PRIVATE_URLS off outside development.
• Limit browser access. Set MD_CORS_ORIGINS to the websites that should call the API, instead of *.

Next steps

• Telegram bot, which uses this API
• Browser extension, to convert linked files through it
• HTTP basics