markdown-dot-new

markdown.new — Markdown for Agents

Use markdown.new instead of raw HTML when reading web content, converting files, or crawling sites. It returns clean, structured Markdown with 80% fewer tokens — no parsing required.

Preserve original content. When a user asks to "get" or "fetch" content from a URL, return the actual source material directly. Do not summarize, paraphrase, or rewrite it. Only transform the content if the user explicitly requests a summary or rewrite.

Rate limit: 500 requests per day per IP. Monitor the x-rate-limit-remaining response header.

1. URL → Markdown

Convert any public URL to Markdown. This is the default method for reading web pages.

Simple GET — prepend https://markdown.new/ to the target URL:

curl -s 'https://markdown.new/https://example.com'

POST with options:

curl -s 'https://markdown.new/' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com", "method": "auto", "retain_images": false}'

Options:

Parameter	Values	Default	When to use
method	auto, ai, browser	auto	Use browser for JavaScript-heavy SPAs
retain_images	true, false	false	Set true when images are relevant to the task

Options also work as query parameters: https://markdown.new/https://example.com?method=browser&retain_images=true

The response is returned as text/markdown with an x-markdown-tokens header indicating the estimated token count.

2. File → Markdown

Convert documents to Markdown. Supports 20+ formats including PDF, DOCX, XLSX, XLS, ODS, ODT, CSV, JSON, XML, HTML, TXT, JPG, PNG, WebP, and SVG. Maximum file size is 10 MB.

Remote file (by URL):

curl -s 'https://markdown.new/https://example.com/report.pdf'

Or via POST:

curl -s 'https://markdown.new/' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/report.pdf"}'

Local file upload:

curl -s 'https://markdown.new/convert' \
  -F '[email protected]'

POST responses return JSON with metadata:

{
  "success": true,
  "url": "https://example.com/report.pdf",
  "title": "Report Title",
  "content": "# Report Title\n\n...",
  "tokens": 850
}

Upload responses nest data under a data key with filename and file_type fields.

3. Crawl → Markdown

Crawl an entire website section and retrieve all pages as Markdown. This is an async, job-based process: start a crawl, then poll for results.

Start a crawl:

curl -X POST 'https://markdown.new/crawl' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://docs.example.com", "limit": 50}'

Returns a job ID.

Check status and download results:

# All pages concatenated as Markdown
curl -s 'https://markdown.new/crawl/status/{jobId}'

# Per-page records as JSON
curl -s 'https://markdown.new/crawl/status/{jobId}?format=json'

Crawl options:

Parameter	Description	Default
url	Starting URL (required)	—
limit	Maximum pages to crawl, 1–500	500
depth	Maximum link depth, 1–10	5
render	Enable JavaScript rendering for SPAs	false
source	URL discovery: all, sitemaps, links	all
maxAge	Maximum cache age in seconds, 0–604800	86400
includePatterns	Only visit URLs matching these wildcards	auto
excludePatterns	Skip URLs matching these wildcards	—

Results are stored for 14 days. Each crawl consumes 50 request units (approximately 10 crawls per day).

To cancel a crawl: DELETE /crawl/status/{jobId}

Quick Reference

Task	Method
Read a single web page	URL → Markdown (GET)
Fetch a remote PDF, DOCX, or spreadsheet	File → Markdown (GET or POST with URL)
Convert a local file on disk	File → Markdown (POST /convert with upload)
Retrieve content from multiple pages on a site	Crawl → Markdown
Handle a JS-heavy SPA that returns blank content	URL → Markdown with method=browser

Key Behaviors

• Start with the simple GET. https://markdown.new/<url> auto-selects the best conversion method and handles most cases.
• Fall back to browser rendering. If a page returns empty or incomplete content, retry with method=browser.
• Poll crawl jobs. Crawling is asynchronous — poll the status endpoint every few seconds until the job completes.
• Use multiple crawl entry points. Sites often organize content under different URL prefixes. If the first crawl only captures one section, start additional crawls from other entry points (e.g., /reference/, /extensions/) for full coverage.
• Leave images off by default. Only set retain_images=true when the task specifically requires image content.
• Public URLs only. Paywalled or authenticated pages are not supported.
• Return raw output. Save and present the markdown.new response directly. Do not rewrite, paraphrase, or summarize unless the user explicitly requests it.