REFETCH(1)                   Refetch Manual                   REFETCH(1)

NAME
  refetch.cloud — reliable web fetching for AI agents and automation

SYNOPSIS
  curl refetch.cloud/html/{url}
  curl refetch.cloud/md/{url}
  curl refetch.cloud/ld+json/{url}
  curl "refetch.cloud/s/news?q={query}"
  curl "refetch.cloud/s/web?q={query}"

DESCRIPTION
  Refetch retrieves publicly accessible web pages and returns them in
  machine-readable formats. Requests are routed through globally
  distributed infrastructure with automatic retries and intelligent
  block detection. Your IP address is never exposed to target sites.

  Each endpoint serves full documentation at its root path.

ENDPOINTS
  /html/{url}         Fetch page as raw HTML
  /md/{url}           Fetch page as clean Markdown
  /ld+json/{url}      Extract JSON-LD structured data
  /s/news?q=          Search news articles (structured JSON)
  /s/web?q=           Search the web (structured JSON)
  /mcp                Connect via Model Context Protocol
  /usage              View your credit balance and usage history
  /limits             View rate limits and pricing
  /llm-integration.md Complete integration guide for AI agents and LLMs

AUTHENTICATION
  All fetch and search endpoints require an API key.

  Headers:
    Authorization  (required)  Bearer YOUR_API_KEY (e.g. Bearer ftch_xxxxxxxx)

  Each request costs 1 credit. Documentation endpoints are free.

  Check your usage:  curl -H "Authorization: Bearer YOUR_KEY" refetch.cloud/usage
  Check limits:      curl refetch.cloud/limits

REQUEST
  URL Parameter:
    {url}              (required)  Full URL with scheme (https://example.com/page)

  Headers:
    X-Block-Patterns   (optional)  Comma-separated custom strings to detect soft blocks.
                                   If any pattern appears in the response body, the request
                                   is retried through a different route.
                                   Example: X-Block-Patterns: premium required,subscribe to read

  Query parameters are forwarded to the target URL.

RESPONSE
  200 OK
    Content-Type: forwarded from upstream (typically text/html)
    Body: raw HTML from the target page

  Response Headers (conditional):
    X-Resolved-URL     Set when a news redirect URL was auto-resolved

ERRORS
  All errors return Content-Type: application/json

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

  Code                       Status  Description
  ─────────────────────────────────────────────────────────────────────
  INVALID_URL                400     URL is malformed or missing scheme
  MISSING_PARAM              400     Required query parameter missing
  CONTENT_TYPE_NOT_ALLOWED   400     Upstream content type not supported
  RESPONSE_TOO_LARGE         400     Upstream response exceeds size limit
  RECURSIVE_PROXY            400     Cannot proxy requests to this service
  SEARCH_NOT_SUPPORTED       400     Search engine result pages not supported
  DOMAIN_RATE_LIMITED        429     Too many requests to target domain
  NO_LD_JSON                 404     No structured data found on page
  RATE_LIMITED               429     Upstream rate limit exceeded
  UPSTREAM_BLOCKED           502     Target site blocked the request
  NEWS_RESOLVE_FAILED        502     Could not resolve news redirect URL
  UPSTREAM_ERROR             502     Upstream fetch failed
  SERVICE_UNAVAILABLE        503     Service temporarily unavailable
  INTERNAL_ERROR             500     Unexpected server error

AI/LLM INTEGRATION
  If you are an AI agent or LLM building an integration, fetch
  /llm-integration.md for complete, machine-readable instructions
  covering all endpoints, error handling, rate limits, and retry logic.

SEE ALSO
  /html, /md, /ld+json, /s/news, /s/web, /mcp, /limits, /llm-integration.md

GETTING STARTED
  You're reading this, so you're probably human. Nice to meet you.

  Your agent needs an API key to use this service.
  Sign up at www.refetch.cloud to get started.
  500 free requests on signup. No credit card required.

  Pricing: $2.50 per 1,000 requests. Pay as you go.

LEGAL
  By using this service you agree to the Terms of Service.

  Terms of Service:  refetch.cloud/tos
  Privacy Policy:    refetch.cloud/privacy