Webpage to Markdown API: convert URLs into clean Markdown for AI workflows.

The short answer

At its simplest, a webpage to Markdown API takes a public URL and gives you Markdown back. Between those two points it has to fetch the HTML, find the part worth keeping, drop the surrounding interface, and translate the remaining elements. You may also see this described as a URL to Markdown API or website to Markdown API.

How does a webpage to Markdown API work?

Most services follow the same broad path, even though their extraction rules differ.

1. Check the address. The service accepts an HTTP or HTTPS URL and rejects destinations it should not reach.
2. Fetch the page. It requests the HTML, handles redirects according to its own rules, and keeps the final source URL. The Fetch API documentation is a useful reference for the request-and-response model.
3. Find the main content. On an article this may be the headline and body. On documentation it may be the central reference panel. Navigation, consent banners, repeated promotions, and recommendation blocks are usually noise.
4. Translate the HTML. Headings, paragraphs, lists, links, tables, images, and code blocks are converted one element at a time.
5. Send back the result. Good responses include the Markdown, title, final URL, status, and any warning the caller needs to see.

The last step depends on which Markdown dialect the service targets. CommonMark covers the core syntax. GitHub Flavored Markdown adds familiar extensions such as pipe tables.

What should the API return?

The Markdown string is only part of the useful response. Without the title and source URL, a clean-looking file can become surprisingly hard to trace a week later.

The example below uses api.example.com only to show the shape of a request. It is not a working Plainmark endpoint; Plainmark does not currently publish an API.

POST /v1/convert
{
  "url": "https://example.com/article"
}

{
  "title": "Example article",
  "source_url": "https://example.com/article",
  "markdown": "# Example article\n\n...",
  "status": "success"
}

Should you use an API or a browser converter?

For one page, an API is often more setup than solution. It starts to earn its place when the same conversion needs to run on a schedule, inside another product, or across a controlled queue.

If the job is one article, guide, or documentation page, Plainmark Web to Markdown keeps the source beside the result. That is also a sensible way to settle your review rules before writing an automated process. The webpage conversion guide covers that manual pass in more detail.

Which failure cases need explicit handling?

JavaScript-rendered content

Sometimes the first response contains little more than an empty application shell. Loading the page in a browser can reveal the article, but it also makes each conversion slower and more expensive to run.

Login pages and paywalls

A login form is not an article. Neither is a subscription message or permission error. Mark these as failed retrievals rather than allowing them into a content index.

Robots and site policies

Automated retrieval still has to follow the relevant access rules and site policies. RFC 9309 documents how robots.txt works, but it does not replace copyright, privacy, contractual, or permission checks.

Unsafe destination URLs

Any server that accepts a URL from a user needs to guard its own network. Private addresses and unexpected schemes should be rejected. The OWASP SSRF prevention guidance explains the risk and the usual defenses.

Wrong content selection

A request can return HTTP 200 and still extract the wrong thing. A page full of navigation, comments, or related links is a retrieval success but a conversion failure.

How should you validate the Markdown before using it?

Read the first result beside the original page before you trust the next hundred. A short review catches most extraction mistakes:

• Does the title match the page?
• Do the H1, H2, and H3 headings form a sensible outline?
• Are both the opening and closing paragraphs present?
• Do links still have useful labels and valid destinations?
• Did lists, tables, code blocks, and meaningful images survive?
• Did navigation, consent text, or promotional blocks slip through?
• Is the final source URL stored with the conversion date?
• Will warnings and incomplete results stop for review?

If the Markdown is headed for retrieval, keep its source information before splitting it into chunks. The RAG-ready Markdown guide covers headings, source links, and useful chunk boundaries.

Frequently asked questions