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:

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 'file=@document.pdf'

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:

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

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.