Documentation

Everything you need to integrate refetch into your agent or application.

Authentication

All fetch and search endpoints require an API key passed via theX-API-Key header.

curl -H "X-API-Key: ftch_your_key" refetch.cloud/md/https://example.com

Each request costs 1 credit. Documentation endpoints and search endpoints called without a q parameter are free. Check your balance anytime:

bash

curl -H "X-API-Key: ftch_your_key" refetch.cloud/usage

json

{
  "key": "ftch_abc1...",
  "credits_remaining": 450,
  "usage": {
    "2026-03-05": { "/md": 30, "/s/web": 12 },
    "2026-03-06": { "/md": 18, "/s/news": 5, "/": 3 }
  }
}

Fetch /html/{url}

Fetch any publicly accessible webpage as raw HTML. The target URL goes directly in the path, including its scheme.

bash

curl -H "X-API-Key: YOUR_KEY" refetch.cloud/html/https://example.com/page

Response

html

<!doctype html>
<html lang="en">
<head>
    <title>Example Domain</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
    <div>
        <h1>Example Domain</h1>
        <p>This domain is for use in documentation examples
        without needing permission. Avoid use in operations.</p>
        <p><a href="https://iana.org/domains/example">Learn more</a></p>
    </div>
</body>
</html>

Query parameters are forwarded to the target. You can pass custom strings via theX-Block-Patterns header to detect soft blocks. If any pattern appears in the response body, refetch treats it as blocked and retries through a different route. Useful for paywalls, login walls, or pages that return 200 OK but show gated content.

bash

curl -H "X-API-Key: YOUR_KEY" \
     -H "X-Block-Patterns: premium required,subscribe to read" \
     "refetch.cloud/html/https://example.com/page?sort=date"

Markdown /md/{url}

Returns clean Markdown optimized for LLM context windows. Scripts, styles, navigation, ads, and cookie banners are stripped. Relative URLs are resolved to absolute.

bash

curl -H "X-API-Key: YOUR_KEY" refetch.cloud/md/https://example.com

Response

markdown

# Example Domain

This domain is for use in documentation examples without needing
permission. Avoid use in operations.

[Learn more](https://iana.org/domains/example)

JSON-LD /ld+json/{url}

Extracts all JSON-LD structured data blocks from a page. Returns a JSON array of parsed objects. Returns 404 if no JSON-LD is found.

bash

curl -H "X-API-Key: YOUR_KEY" refetch.cloud/ld+json/https://en.wikipedia.org/wiki/Artificial_intelligence

Response

json

[
  {
    "@context": "https://schema.org",
    "@type": "Article",
    "name": "Artificial intelligence",
    "url": "https://en.wikipedia.org/wiki/Artificial_intelligence",
    "author": {
      "@type": "Organization",
      "name": "Contributors to Wikimedia projects"
    },
    "publisher": {
      "@type": "Organization",
      "name": "Wikimedia Foundation, Inc."
    },
    "datePublished": "2001-10-08T16:55:49Z",
    "headline": "field of computer science that develops and studies software enabling machines to exhibit intelligent behavior"
  }
]

Web search /s/web

Structured web search results as JSON.

bash

curl -H "X-API-Key: YOUR_KEY" "refetch.cloud/s/web?q=openai+api+pricing"

Response

json

{
  "query": "openai api pricing",
  "params": { "country": "US", "lang": "en" },
  "count": 10,
  "results": [
    {
      "title": "API Pricing - OpenAI",
      "url": "https://openai.com/api/pricing/",
      "snippet": "Pricing above reflects standard processing rates for context lengths under 270K..."
    },
    {
      "title": "OpenAI API Pricing (Updated 2026) - All Models & Token Costs",
      "url": "https://pricepertoken.com/pricing-page/provider/openai",
      "snippet": "Complete OpenAI API pricing guide for 2026. Compare all models with per-token costs..."
    }
  ]
}

Parameters

qrequiredSearch querycountryoptionalISO 3166-1 alpha-2 code (default: US)langoptionalISO 639-1 code (auto-selected from country)whenoptionald (day), w (week), m (month), y (year)

News search /s/news

Search news articles across 20+ countries.

bash

curl -H "X-API-Key: YOUR_KEY" "refetch.cloud/s/news?q=AI&country=US&when=7d"

Response

json

{
  "query": "AI",
  "params": { "country": "US", "lang": "en", "when": "7d" },
  "count": 100,
  "articles": [
    {
      "title": "Productivity surges on investment in artificial intelligence",
      "url": "https://www.latimes.com/business/story/2026-03-05/...",
      "source": { "name": "Los Angeles Times", "url": "https://www.latimes.com" },
      "publishedAt": "2026-03-05T15:37:55Z"
    },
    {
      "title": "Africa emerges as new arena in US-China competition over AI",
      "url": "https://www.scmp.com/news/us/article/3345483/...",
      "source": { "name": "South China Morning Post", "url": "https://www.scmp.com" },
      "publishedAt": "2026-03-04T20:10:11Z"
    }
  ]
}

Parameters

qrequiredSearch querycountryoptionalISO 3166-1 alpha-2 code (default: US)langoptionalISO 639-1 code (auto-selected from country)whenoptional1d, 7d, 30d, 180dlimitoptionalMax results, 1-100 (default: 100)

Supported countries

US, GB, CA, AU, AE, SE, NO, DK, FI, DE, AT, CH, FR, ES, IT, NL, BE, PT, PL, CZ, IL, SA. The language is auto-selected from the country code but can be overridden with the lang parameter.

MCP /mcp

Connect any MCP-compatible client to refetch. Claude Desktop, Cursor, or custom agents. All endpoints available as tools.

json

{
  "mcpServers": {
    "refetch": {
      "url": "https://refetch.cloud/mcp",
      "headers": {
        "X-API-Key": "ftch_your_key_here"
      }
    }
  }
}

Available tools

fetchFetch any URL as clean Markdownfetch_htmlFetch raw HTML sourcefetch_structured_dataExtract JSON-LD schema.org datasearch_webWeb search with structured resultssearch_newsNews search with sources and datescheck_usageCheck credit balance and usage (free)

Errors

All errors return JSON with a code and message:

json

{ "error": { "code": "ERROR_CODE", "message": "description" } }

Credits are deducted before the upstream request is made. If the request fails after that point, the credit is still consumed. Errors marked with billed below will cost 1 credit.

Authentication

Code	Status		What to do
UNAUTHORIZED	401	free	Missing X-API-Key header. Add it to every request.
INVALID_API_KEY	401	free	Key not recognized. Check for typos or regenerate from your console.
INSUFFICIENT_CREDITS	402	free	Balance is zero. Top up at www.refetch.cloud or check /usage.

Client errors

Code	Status		What to do
INVALID_URL	400	billed	URL is malformed, missing scheme, or points to a private IP. Use a full public URL with https://.
MISSING_PARAM	400	free	A required parameter is missing. Search endpoints need a q parameter.
CONTENT_TYPE_NOT_ALLOWED	400	billed	The target returned an unsupported content type. PDFs, images, and binary files are not supported.
RESPONSE_TOO_LARGE	400	billed	Response body exceeds 10 MB. Try requesting a more specific page.
RECURSIVE_PROXY	400	billed	You tried to fetch from refetch.cloud itself. Don't do that.
NO_LD_JSON	404	billed	Page was fetched successfully but contains no JSON-LD structured data. Try /md/ instead.
NOT_FOUND	404	free	Unknown endpoint. Check the path.

Rate limits

Code	Status		What to do
KEY_RATE_LIMITED	429	free	You exceeded your per-key limit (100/s burst, 1,000/min). Back off and spread requests over time.
DOMAIN_RATE_LIMITED	429	varies	Too many requests to the same domain. A 60-second penalty starts. Retries during the penalty window cost 1 credit each.

Upstream errors

Code	Status		What to do
UPSTREAM_BLOCKED	502	billed	The target site blocked the request. Wait and retry, or use X-Block-Patterns to detect soft blocks.
UPSTREAM_ERROR	502	billed	The target site is down or returned an invalid response. Retry after a few seconds.
RATE_LIMITED	429	billed	Upstream service is rate-limiting. Wait before retrying.

Server errors

Code	Status		What to do
SERVICE_UNAVAILABLE	503	free	Service is temporarily unavailable. Retry in a few seconds.
CAPACITY_EXCEEDED	503	free	Service is at maximum capacity. Back off briefly and retry.
INTERNAL_ERROR	500	billed	Unexpected server error. If this persists, contact support.

Rate limits

Two independent rate limits apply to every request. Both use fixed-window counters.

Per-key limits

Each API key is limited to 100 requests/second burst and 1,000 requests/minute sustained. Requests that exceed these limits return KEY_RATE_LIMITED (429) and are not charged.

Per-domain limits

Each target domain has its own rate limit. You may receive DOMAIN_RATE_LIMITED (429) even if you haven't hit your per-key limit. When this happens, a 60-second penalty window begins. The first hit is free. Requests to the same domain during the penalty window cost 1 credit each, so back off immediately.

Response headers

Successful responses include an X-Credits-Remaining header with your current balance. No rate limit headers are returned. Use the /usage endpoint to check your balance and request history, or /limits for machine-readable rate limit and credit information (no auth required).