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.
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
{
"url": "https://example.com/blog/article",
"saveToHistory": false,
"options": {
"includeLinks": true,
"includeImages": true,
"includeMetadata": true,
"mainContentSelector": "article",
"enableJsRendering": false
}
}Response
{
"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
{
"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
{
"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:
Authorization: Bearer wtm_live_your_api_key_hereYou 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 Tier | Monthly Credits | Concurrency Limit | Batch URL Max |
|---|---|---|---|
| Free | 10 requests / day | 1 concurrent request | 5 URLs |
| Pro ($9/mo) | 2,000 credits | 2 concurrent requests | 100 URLs |
| Plus ($19/mo) | 6,000 credits | 5 concurrent requests | 200 URLs |
| Project Pass ($15) | Full Plus access for 30 days | 5 concurrent requests | 200 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
curl -X POST https://webtomarkdown.org/api/v1/convert \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'TypeScript / Node.js
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
import requests
resp = requests.post(
"https://webtomarkdown.org/api/v1/convert",
json={"url": "https://example.com/docs"}
)
print(resp.json()["data"]["markdown"])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.
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.