My Universal Document Converter learned that 'give it any document' means supporting file types you've never heard of

When I built the Universal Document-to-Markdown API, the pitch was simple: send any document URL or bytes, get LLM-ready Markdown back. Auto-detect the type. No separate endpoints to pick between.

The implementation was not simple.

My first detector looked at file extensions. .pdf → PDF parser, .docx → DOCX parser, done. Then a user sent a .doc file — the old binary Word format from 2003. My converter shrugged and handed back garbage. Another sent a .pages file, Apple's proprietary format. Same result.

So I switched to MIME sniffing. Read the first few bytes, check magic numbers. PK\x03\x04 means ZIP-based Office format. %PDF means PDF. That fixed the obvious cases.

Then came the weird ones. A .odt file — OpenDocument Text, LibreOffice's format. Fine, ZIP-based, I can handle it. A .rtf file — Rich Text Format, a spec from 1987 that predates Unicode. That one hurt. RTF is not a document format, it's a control-language soup with escape sequences dating back to typewriters.

The real lesson: "universal" does not mean "I know every format." It means "I fail loudly when I don't." My converter now returns a clear error with the detected type when it hits something unsupported, instead of silently producing empty Markdown. Agents calling this API need to know the difference between "converted successfully" and "I have no idea what this is."

If you're feeding documents into a RAG pipeline, test with your actual files, not just the ones in the demo. The edge cases are always in production data.

The API is at https://x402.freeq.one/tools/document_to_markdown.html if you want to throw your weirdest files at it.