TypeScript 97.5%
SQL 1.4%
Python 0.8%
1import type { Metadata } from "next";2import { CodeBlock } from "@/components/ui/code-block";3import { DocPage } from "@/components/docs/doc-page";4import { A, CardGrid, Code, H2, H3, Lead, Li, LinkCard, P, Strong, Table, TBody, Td, Th, THead, Tr, Ul } from "@/components/docs/prose";5import { Callout } from "@/components/docs/callout";6import { Badge } from "@/components/ui/badge";78export const metadata: Metadata = {9 title: "Introduction",10 description: "What Fetcha is, how to think about it, what is live today and what is coming next.",11};1213const LIVE: Array<[string, string]> = [14 ["POST /v1/fetch", "Fetch any public http(s) URL through the routing engine. HTML, text, Markdown, JSON or raw output, page metadata and links."],15 ["Managed browser", "browser: true renders the page in a headless Chromium on the same route; blocked HTTP attempts escalate to it automatically (browser_fallback)."],16 ["Crawl & map", "POST /v1/crawl turns a site into Markdown/text/HTML as an asynchronous job; POST /v1/map lists a site's URLs."],17 ["Residential network + auto", "The residential class is live. auto currently resolves to residential."],18 ["Geolocation", "Country targeting (ISO 3166-1 alpha-2), with region and city hints."],19 ["Sessions", "Sticky exit identity for 60 to 1,800 seconds via /v1/sessions."],20 ["Retries & escalation", "Automatic retry with a new exit IP and header profile, expanded block detection (Cloudflare, DataDome, PerimeterX, Akamai, Kasada, Imperva, AWS WAF, soft blocks), per-domain intelligence, circuit breakers."],21 ["Account endpoints", "GET /v1/me and GET /v1/usage for key introspection and monthly usage."],22 ["Dashboard", "Projects, API keys, request logs with request IDs, crawls, usage and a Playground."],23];2425const SOON: Array<[string, string]> = [26 ["Browser actions", "POST /v1/browser (click, type, scroll, evaluate). Today it returns BROWSER_UNAVAILABLE. Rendered fetches are live."],27 ["Structured extraction", "POST /v1/extract. Today it returns INVALID_REQUEST with an explanatory message."],28 ["Datacenter, ISP and mobile classes", "Requesting them explicitly returns NETWORK_UNAVAILABLE until they launch."],29 ["Webhooks", "Event delivery signed with HMAC-SHA256 (including crawl webhook_url). Not delivered yet."],30 ["CLI", "A command-line client. Not available."],31 ["Teams & invitations", "Multi-member organizations."],32 ["Published SDK packages", "@fetcha/sdk on npm and fetcha on PyPI. Both exist as source in the repository today."],33];3435export default function IntroductionPage() {36 return (37 <DocPage38 path="/docs"39 title="Introduction"40 description="Fetcha is Intelligent Web Access Infrastructure: one HTTP API that fetches web pages for you and figures out which network, exit location and retry strategy each target needs."41 status="Stable"42 >43 <Lead>44 The mental model is deliberately simple: <Strong>you give Fetcha a URL, Fetcha figures out how to access it.</Strong> You do not manage proxies, rotate IPs, detect block pages or45 tune retry loops. You send one request and receive the page, the final URL, headers, cookies and metadata describing how the request was served.46 </Lead>4748 <H2>How it works</H2>49 <P>50 Every call to <Code>POST /v1/fetch</Code> goes through the same pipeline:51 </P>52 <Ul>53 <Li>54 <Strong>Validate.</Strong> The body is checked against a strict schema; unknown fields are rejected. Plan limits are applied (timeout is capped, network classes are gated).55 </Li>56 <Li>57 <Strong>Protect.</Strong> Only <Code>http</Code> and <Code>https</Code> are allowed. Localhost, private, link-local, cloud-metadata and internal hostnames are refused, and every redirect hop is58 re-validated before it is followed.59 </Li>60 <Li>61 <Strong>Route.</Strong> The routing engine scores the available routes for the target domain using historical success, cost, latency, network health, geography and session stability, then62 orders them from cheapest to most reliable.63 </Li>64 <Li>65 <Strong>Execute and escalate.</Strong> The request is sent through the best route with a complete browser header profile. If the response looks like a block page (403, 429, captcha, anti-bot66 challenge, WAF page, soft 200 block), Fetcha retries with a fresh exit identity or an alternate route, and renders the page in the managed browser when the block is a JavaScript67 challenge, all within the request's retry budget and single overall timeout.68 </Li>69 <Li>70 <Strong>Learn.</Strong> Each attempt updates a per-domain profile so future requests to the same site start from the route most likely to succeed.71 </Li>72 </Ul>7374 <H2>Base URL</H2>75 <P>The API is served on the same domain as the website. There is no separate API host to configure.</P>76 <CodeBlock code={`https://www.fetcha.co`} lang="text" copy />77 <P>78 All endpoints are versioned under <Code>/v1</Code>. Requests and responses are JSON (<Code>Content-Type: application/json</Code>). Health probes are public at{" "}79 <Code>/api/health</Code> and <Code>/api/ready</Code>.80 </P>8182 <H2>Your first request</H2>83 <P>84 Authenticate with a Bearer API key and post a URL. A minimal call looks like this; see the <A href="/docs/quickstart">Quickstart</A> for the full walkthrough and the{" "}85 <A href="/docs/fetch">Fetch API</A> reference for every field.86 </P>87 <CodeBlock88 lang="bash"89 code={`curl https://www.fetcha.co/v1/fetch \\90 -X POST \\91 -H "Authorization: Bearer $FETCHA_API_KEY" \\92 -H "Content-Type: application/json" \\93 -d '{"url": "https://example.com", "country": "CA", "format": "text"}'`}94 />9596 <H2>Request IDs</H2>97 <P>98 Every response, successful or not, carries an <Code>X-Fetcha-Request-ID</Code> header of the form <Code>req_…</Code>. Fetch responses repeat it as <Code>request_id</Code> in the body, and99 error envelopes include it as <Code>error.request_id</Code>. The same identifier appears in your dashboard request log. Quote it when you write to{" "}100 <A href="mailto:support@fetcha.co">support@fetcha.co</A>: it lets us find the exact attempt sequence for your call.101 </P>102 <CodeBlock103 lang="text"104 code={`HTTP/1.1 200 OK105Content-Type: application/json; charset=utf-8106X-Fetcha-Request-ID: req_k3j9d0f2a8b1c7e4107X-Fetcha-Version: 0.1.0108Cache-Control: no-store`}109 />110111 <H2>What is live today</H2>112 <P>113 Fetcha is a private platform: access is granted by invitation and every account runs on the single unlimited plan. The table below is the authoritative list of what you can call right114 now; the section after it lists what is planned. The docs never describe a capability as working unless it is.115 </P>116 <Table>117 <THead>118 <Tr>119 <Th>Capability</Th>120 <Th>Status</Th>121 <Th>Notes</Th>122 </Tr>123 </THead>124 <TBody>125 {LIVE.map(([name, note]) => (126 <Tr key={name}>127 <Td mono>{name}</Td>128 <Td>129 <Badge variant="success" dot>130 Live131 </Badge>132 </Td>133 <Td>{note}</Td>134 </Tr>135 ))}136 </TBody>137 </Table>138139 <H3>Coming soon</H3>140 <Table>141 <THead>142 <Tr>143 <Th>Capability</Th>144 <Th>Status</Th>145 <Th>Current behaviour</Th>146 </Tr>147 </THead>148 <TBody>149 {SOON.map(([name, note]) => (150 <Tr key={name}>151 <Td mono>{name}</Td>152 <Td>153 <Badge variant="warning" dot>154 Coming soon155 </Badge>156 </Td>157 <Td>{note}</Td>158 </Tr>159 ))}160 </TBody>161 </Table>162 <Callout variant="info" title="Network classes">163 Fetcha exposes <Code>network</Code> classes (<Code>auto</Code>, <Code>datacenter</Code>, <Code>residential</Code>, <Code>isp</Code>, <Code>mobile</Code>) rather than the identity of the upstream164 networks behind them. Debug metadata refers to routes by neutral aliases such as <Code>network-a</Code>.165 </Callout>166167 <H2>Where to go next</H2>168 <CardGrid>169 <LinkCard href="/docs/quickstart" title="Quickstart" description="Create a key and make your first request in under five minutes." />170 <LinkCard href="/docs/fetch" title="Fetch API reference" description="Every request field, the response shape, size limits and redirect rules." />171 <LinkCard href="/docs/browser" title="Browser" description="Rendered fetches, automatic escalation on JavaScript challenges, screenshots." />172 <LinkCard href="/docs/crawl" title="Crawl & Map" description="Turn a whole site into Markdown with an asynchronous job, or list its URLs." />173 <LinkCard href="/docs/networks" title="Network selection" description="What auto does, how routes are scored and what each class means." />174 <LinkCard href="/docs/errors" title="Errors" description="All error codes with HTTP status, meaning and how to recover." />175 <LinkCard href="/docs/sdks" title="SDKs" description="JavaScript/TypeScript and Python clients, installed from source." />176 <LinkCard href="/docs/examples" title="Examples" description="Eight recipes covering sessions, POST bodies, blocks, concurrency and debugging." />177 </CardGrid>178 </DocPage>179 );180}181