Documentation

Everything you need to convert URLs to Markdown.

# Quickstart

Convert any URL to Markdown in one request:

$ curl https://grep.md/https://example.com

# With grep — search for "install" in the page
$ curl "https://grep.md/https://docs.example.com?grep=install"

# Extract only code blocks
$ curl "https://grep.md/https://docs.example.com?extract=code"

# JSON response with metadata and timing
$ curl "https://grep.md/https://example.com?format=json&meta=true"

# URL Formats

grep.md/{url} Path prefix (primary)
grep.md/api/v1/convert?url={encoded-url} Query parameter (REST API)

# Parameters

Param Type Description
grep string Search pattern (text or regex)
grep_regex boolean Treat grep as regex pattern
grep_case boolean Case-sensitive grep (default: false)
grep_invert boolean Invert grep — return non-matching lines
grep_context integer Lines of context around grep matches
extract enum code, links, tables, headings, images, metadata
selector string CSS selector to extract specific elements
remove string CSS selector to remove elements before conversion
format enum md (default), json, text, llm
meta boolean Include YAML frontmatter with metadata
render boolean Force browser rendering (for SPAs)
pages integer Multi-page crawl depth (follow links)
nocache boolean Bypass cache, fetch fresh content

# Response Formats

Markdown (default)

Content-Type: text/markdown; charset=utf-8

# Page Title

Page content as clean Markdown...

JSON (?format=json)

{
  "url": "https://example.com",
  "title": "Example Domain",
  "markdown": "# Example Domain\n\nThis domain is for...",
  "metadata": {
    "description": "...",
    "wordCount": 42,
    "language": "en",
    "siteName": "Example"
  },
  "timing": {
    "total": 847,
    "fetch": 312,
    "extract": 45,
    "convert": 23
  },
  "cache": {
    "hit": false,
    "tier": null
  }
}

LLM (?format=llm)

Stripped of images, links, and formatting — optimized for LLM context windows.

# Response Headers

X-GrepMD-Cache Cache tier hit: MISS, L1, L2, L3
X-GrepMD-Request-Id Unique request identifier
X-GrepMD-RateLimit-Limit Requests per minute allowed
X-GrepMD-RateLimit-Remaining Requests remaining in window

# Authentication

Anonymous access is available with basic rate limits (10 req/min). For higher limits, sign up for an API key. 

# Pass your API key via Authorization header
$ curl -H "Authorization: Bearer gm_live_..." \
    "https://grep.md/https://example.com"

API keys use the prefix gm_live_ for production and gm_test_ for testing. Generate keys from the Dashboard.

# Rate Limits

Tier Requests/min Credits/month
Anonymous 10 —
Free 30 500
Pro ($9/mo) 100 10,000
Team ($29/mo) 300 50,000
Agent ($99/mo) 500 100,000
Enterprise Custom Custom

# Code Examples

cURL

# Basic conversion
$ curl https://grep.md/https://example.com

# Grep for a pattern
$ curl "https://grep.md/https://docs.example.com?grep=installation"

# Extract all links as JSON
$ curl "https://grep.md/https://example.com?extract=links&format=json"

# Force browser rendering for SPAs
$ curl "https://grep.md/https://spa-app.com?render=true"

JavaScript / TypeScript

// Basic conversion
const res = await fetch('https://grep.md/https://example.com');
const markdown = await res.text();

// With API key and parameters
const res2 = await fetch(
  'https://grep.md/https://example.com?grep=install&format=json',
  { headers: { Authorization: 'Bearer gm_live_...' } }
);
const data = await res2.json();
console.log(data.markdown, data.timing);

Python

import requests

# Basic conversion
r = requests.get("https://grep.md/https://example.com")
print(r.text)

# With parameters
r = requests.get(
    "https://grep.md/https://example.com",
    params={"grep": "install", "format": "json"},
    headers={"Authorization": "Bearer gm_live_..."}
)
data = r.json()
print(data["markdown"])

# Error Codes

400 Invalid URL or parameters
401 Invalid or missing API key
403 URL blocked (robots.txt or DMCA)
429 Rate limit exceeded (check Retry-After header)
502 Target URL unreachable or timed out