PDF to HTML: what 'HTML' should mean from a PDF API

Type “PDF to HTML” into Google and you get tools that screenshot every page, paste an invisible text layer underneath, and call it a day. That output is fine if you only ever wanted a static archive. It is awful if what you actually want is to read the PDF on your phone, share it as a link, ask questions of it, or hand it to a coding agent.

This is a quick tour of the four PDF→HTML artifacts okraPDF can hand you, what each is for, and the curl recipe to get one.

The status quo: HTML as a screenshot

The dominant pieces of PDF-to-HTML software — pdf2htmlEX, the “Save as Web Page” option in Acrobat, online converters that wrap them — were designed in an era when faithfully reproducing a printed page on screen was the goal. They emit one big <canvas> per page, an absolute-positioned text layer for selection, and a font cache that is usually broken. The result is technically HTML and practically a PDF in disguise.

That output answers the wrong question. Nobody opens a PDF in 2026 and thinks “I wish this was a slightly worse PDF inside an iframe.” They want something they can do something with: read on a small screen, link to a paragraph, send to a coworker, feed to an LLM, embed in an internal dashboard.

HTML is back, but as a richer surface

Thariq Shihipar wrote a popular piece called The Unreasonable Effectiveness of HTML arguing that HTML — not Markdown — is the right output format from a coding agent today. HTML carries tabular data, design tokens, SVG illustrations, embedded interactivity, and is shareable as a link. Markdown stops at a few hundred lines of text.

The same logic applies to a PDF parser. The job of “turn this PDF into something useful” doesn’t end at OCR. It ends when the consumer — a human, an agent, a teammate — has an artifact they can read, share, query, and edit. Several different artifacts, in fact. There isn’t one HTML output that serves all of them.

The four flavors of HTML okraPDF ships

When you POST a PDF to okraPDF, the API doesn’t emit one HTML file. It emits four artifacts, each tuned for a different consumer.

1. Hosted HTML — a shareable link

The simplest flavor: upload a PDF, get a public URL on okrapdf.com (or your own subdomain) that wraps the original in a clean responsive HTML page with a viewer. No screenshot conversion, no text-layer hacks — the PDF is the PDF, and the HTML is the chrome around it.

# 1. Upload the file (returns a file_id)
DOC_ID=$(curl -sX POST https://api.okrapdf.com/v1/files \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -F "file=@quarterly-report.pdf" | jq -r .file_id)

# 2. Publish it as a hosted page
curl -sX POST https://api.okrapdf.com/v1/host \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"file_id\": \"$DOC_ID\", \"namespace\": \"q3-2026\"}"
# → { id, namespace: "q3-2026", url: "https://q3-2026.<your-tenant>.okrapdf.com" }

Built for the “I need to share a PDF and I don’t want to email a 40MB attachment” case. The /host page has a no-code playground that wraps both calls.

2. Reader output — semantic Markdown that renders to HTML

For the AI-consumption case (RAG, summarization, agents), what you want isn’t a faithful page reproduction — it’s the document’s semantics. okraPDF’s parser produces Markdown with preserved heading hierarchy, tables as Markdown tables, and inline figure references. That Markdown trivially renders to clean HTML.

curl https://api.okrapdf.com/v1/documents/$DOC_ID/full.md \
  -H "Authorization: Bearer $OKRA_API_KEY"
# returns Markdown — pipe through any renderer for HTML

The same endpoint takes ?pages=1-3 for slices.

3. Embeddable HTML — interactive surfaces on top of the PDF

Sometimes you want to wrap the PDF in something more than a viewer: a page-turn flipbook, an annotated walkthrough, a chat-the-document side panel, a dashboard that overlays extracted data. These are full HTML apps that treat the PDF as a backing store. okraPDF publishes them to embed.okrapdf.com/e/{runId} via a single endpoint.

curl -X POST https://api.okrapdf.com/v1/documents/$DOC_ID/embed \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "html": "<!doctype html>...", "publish": true }'
# → { embedUrl: "https://embed.okrapdf.com/e/run_..." }

The HTML is yours — bring any framework, any chrome. CSP-sandboxed by origin so cookies/auth never leak in.

4. Configurable HTML — throwaway editors that produce JSON

The fourth flavor is meta. Some API calls take JSON bodies that are painful to write by hand — redaction rectangles, extract-schema field placement, flipbook tuning, parser knobs. Instead of a UI product for each, okraPDF gives you the pattern: a single self-contained HTML file you open via file://, click through, and copy as JSON.

A redaction-box editor is a few hundred lines of HTML that loads page images, lets you drag rectangles, and exports a list of normalized bboxes. A schema builder for /v1/extract drags fields onto PDF regions and emits a JSON Schema body. Both are forks of one starter template.

The pattern, with two starter templates, lives in our skills repo under okra-html-spinup (with okra-html-redact-editor and okra-html-schema-builder as concrete instances). Inspired by Thariq’s “copy as JSON” trick. Works for any config that’s text-hostile — coordinates, regex, cron, color easing, schema field placement.

Quick start: PDF in, four artifacts out

Mint an API key, upload a PDF, hit any of the four endpoints. The free tier covers the first batch of docs each month, no card up front.

# 1. Upload (returns a file_id)
DOC_ID=$(curl -sX POST https://api.okrapdf.com/v1/files \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -F "file=@paper.pdf" | jq -r .file_id)

# 2a. Hosted page
curl -sX POST https://api.okrapdf.com/v1/host \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"file_id\": \"$DOC_ID\", \"namespace\": \"my-doc\"}"

# 2b. Reader markdown
curl -s "https://api.okrapdf.com/v1/documents/$DOC_ID/full.md" \
  -H "Authorization: Bearer $OKRA_API_KEY"

# 2c. Embed your own HTML wrapper
curl -X POST "https://api.okrapdf.com/v1/documents/$DOC_ID/embed" \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"html\": \"...\", \"publish\": true}"

Get an API key

Free tier, no card. Hosted pages, reader markdown, embed runs, and the throwaway-editor pattern all included. Mint a key on /host.

---

Further reading: The Unreasonable Effectiveness of HTML (Thariq Shihipar, 2026) · /host overview