Developer Guideswebsite to markdown api

How to Convert Website URLs to Markdown with an API

Learn how a Website to Markdown API works, including URL extraction, HTML conversion, batch processing, authentication, and error handling.

WebToMarkdown Team· Platform Engineering & API
8 min read
#API#REST#Developer#cURL#Integration

What Is a Website to Markdown API?

A Website to Markdown API is a programmatic web service that accepts a target URL, executes the HTTP request, strips ads and navigation noise, and returns clean, structured Markdown in a structured JSON response.

Instead of managing your own fleet of headless browsers, proxy rotations, and complex HTML parsing heuristics, developers can make a single REST API call and receive clean text ready for LLMs, search engines, or document databases.


Single URL Conversion Endpoint

Request

  • Endpoint: POST /api/v1/convert
  • Content-Type: application/json
json
{
  "url": "https://example.com/blog/article",
  "saveToHistory": false,
  "options": {
    "includeLinks": true,
    "includeImages": true,
    "includeMetadata": true,
    "mainContentSelector": "article",
    "enableJsRendering": false
  }
}

Response

json
{
  "code": 0,
  "message": "ok",
  "data": {
    "title": "Example Article Title",
    "url": "https://example.com/blog/article",
    "markdown": "# Example Article Title\n\nClean article content...",
    "estimatedTokens": 420,
    "cleaningAudit": {
      "removedNavElements": 3,
      "removedFooterElements": 1,
      "removedAdsCount": 4,
      "removedScriptsAndStyles": 18
    },
    "durationMs": 680
  }
}

Batch URL Conversion Endpoint

When migrating multiple pages or scraping full documentation sites, use the batch endpoint:

Request

  • Endpoint: POST /api/v1/convert/batch
  • Content-Type: application/json
json
{
  "urls": [
    "https://example.com/docs/intro",
    "https://example.com/docs/install",
    "https://example.com/docs/api"
  ],
  "profile": "standard",
  "frontmatter": true,
  "mode": "readability",
  "render": "auto",
  "timeout_ms": 30000,
  "max_chars": 200000,
  "fail_fast": false
}

Response

json
{
  "code": 0,
  "message": "ok",
  "data": {
    "request_id": "req_849204",
    "file_id": 402,
    "file_name": "batch_export_20261115.zip",
    "size": 42800,
    "download_url": "https://signed.webtomarkdown.org/downloads/batch_export.zip",
    "expires_at": "2026-11-16T12:00:00Z",
    "summary": {
      "total": 3,
      "succeeded": 3,
      "failed": 0
    },
    "failed": []
  }
}

Authentication and API Keys

API requests are authenticated by passing an API key in the authorization header:

http
Authorization: Bearer wtm_live_your_api_key_here

You can generate and revoke API keys from your Account Dashboard > API Keys. Keys are only displayed in full once upon creation.


Rate Limits and Usage Credits

Plan TierMonthly CreditsConcurrency LimitBatch URL Max
Free10 requests / day1 concurrent request5 URLs
Pro ($9/mo)2,000 credits2 concurrent requests100 URLs
Plus ($19/mo)6,000 credits5 concurrent requests200 URLs
Project Pass ($15)Full Plus access for 30 days5 concurrent requests200 URLs

Error Handling and HTTP Status Codes

  • 400 Bad Request: Malformed JSON or invalid URL format (e.g. missing https://).
  • 401 Unauthorized: Missing or invalid API key.
  • 403 Forbidden: The requested feature (like JS Rendering) requires a higher tier plan.
  • 422 Unprocessable Entity: Target webpage unreachable or returned a 404/500 upstream status.
  • 429 Too Many Requests: Account rate limit or monthly credit quota exceeded.

Implementation Examples

cURL

bash
curl -X POST https://webtomarkdown.org/api/v1/convert \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

TypeScript / Node.js

typescript
const response = await fetch("https://webtomarkdown.org/api/v1/convert", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/docs" }),
});

const result = await response.json();
console.log(result.data.markdown);

Python

python
import requests

resp = requests.post(
    "https://webtomarkdown.org/api/v1/convert",
    json={"url": "https://example.com/docs"}
)
print(resp.json()["data"]["markdown"])
Product Tool

Explore the WebToMarkdown API

Start converting public web pages and batch URLs programmatically with simple JSON requests and fast response times.

Frequently Asked Questions

How fast is the conversion API?

Static pages generally convert in 400ms to 900ms. Pages requiring JavaScript browser rendering take between 2s and 4s.

Can the API handle JavaScript-heavy Single Page Apps?

Yes. Enabling `render: "auto"` or `"always"` spins up an edge browser session to render dynamic DOM nodes prior to conversion.

W

WebToMarkdown Team

Platform Engineering & API at WebToMarkdown

Dedicated to helping developers, AI researchers, and knowledge workers extract, clean, and convert unstructured web content into portable Markdown.

Related Articles & Tutorials

All articles
Developer Guides9 min read
Build your own Python web-to-markdown pipeline with requests, BeautifulSoup, and markdownify, or connect to the WebToMarkdown API for production-grade scraping.
Website Conversion10 min read
Need to download an entire documentation portal or blog into Markdown? Discover how to gather sitemap URLs, run batch conversions, and package thousands of pages into clean Markdown archives.
AI & LLM10 min read
Sending documents as Markdown is 40%–80% more token-efficient and cost-effective than sending PDFs or Word files to LLMs. Discover how to eliminate the PDF vision tax, format tables and headings, and cut token costs.