# Social Fetch API - Web endpoints
# Base URL: https://api.socialfetch.dev
# Auth: x-api-key header (sfk_...)
# Full catalog: https://www.socialfetch.dev/llms-endpoints.txt | JSON: https://www.socialfetch.dev/llms.json
# Docs hub: https://www.socialfetch.dev/docs/api | OpenAPI: https://www.socialfetch.dev/openapi.json

5 documented Web operations. Do not invent paths - only the routes below (and their linked markdown pages) are supported.

## GET /v1/web/search
Search the web
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/web/search/get.mdx
SDK: client.web.search({ query: "Social media scraping API", region: "US" })
Parameters:
- query (required, string) - Search query text to run against the public web.
- region (optional, string) - ISO 3166-1 country code for localized results (e.g. US, GB, CA).
- datePosted (optional, string, enum: last-hour | last-day | last-week | last-month | last-year) - Optional filter by when results were posted.
- page (optional) - Page number (1-based). Defaults to 1 when omitted.
curl "https://api.socialfetch.dev/v1/web/search?query=social media scraping API" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/web/markdown
Generate web page markdown
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/web/markdown/get.mdx
SDK: client.web.getMarkdown({ url: "https://www.socialfetch.dev/" })
Parameters:
- url (required, string) - Web page URL to fetch.
- filter (optional, string, enum: fit | raw | bm25) - Content filter strategy for markdown extraction.
- query (optional, string) - Optional query string used by the bm25 filter to rank relevant content.
- cacheMode (optional, string, enum: enabled | bypass | write_only) - Cache behavior. Defaults to enabled.
Outcome field: `data.lookupStatus` in `found`, `restricted`
Empty results: `lookupStatus: restricted` means bot/access protection blocked the fetch; content fields are null.
curl "https://api.socialfetch.dev/v1/web/markdown?url=https://www.socialfetch.dev" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/web/ask
Ask a question about a web page
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/web/ask/get.mdx
SDK: client.web.ask({ url: "https://www.socialfetch.dev/", q: "What is this page about?" })
Parameters:
- url (required, string) - Web page URL to fetch.
- q (required, string) - Natural-language question to answer about the page content.
Outcome field: `data.lookupStatus` in `found`, `restricted`
Empty results: `lookupStatus: restricted` means bot/access protection blocked the fetch; `answer` is null.
curl "https://api.socialfetch.dev/v1/web/ask?url=https://www.socialfetch.dev&q=What is this page about?" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/web/html
Generate web page HTML
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/web/html/get.mdx
SDK: client.web.getHtml({ url: "https://www.socialfetch.dev/" })
Parameters:
- url (required, string) - Web page URL to fetch.
Outcome field: `data.lookupStatus` in `found`, `restricted`
Empty results: `lookupStatus: restricted` means bot/access protection blocked the fetch; `html` is null.
curl "https://api.socialfetch.dev/v1/web/html?url=https://www.socialfetch.dev" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/web/crawl
Crawl web pages
Credit cost: 1 credit per URL requested. Up to 5 URLs per request (5 credits max).
Docs: https://www.socialfetch.dev/docs/api/v1/web/crawl/get.mdx
SDK: client.web.crawl({ urls: ["https://www.socialfetch.dev/"] })
Parameters:
- url (required, array) - URLs to crawl. Repeat the `url` query parameter for multiple pages (max 5).
curl "https://api.socialfetch.dev/v1/web/crawl?url=https://www.socialfetch.dev" \
  -H "x-api-key: YOUR_API_KEY"