# Sofya > Web search, fetch, extract and research API for AI agents. One API key, four tools, clean markdown output. REST and MCP. Sofya gives agents four web tools. Every successful tool response includes `credits_used` and `credits_remaining`. - **Search** (`POST /v1/search`): web search that returns extracted page content, not just snippets. 1 credit ($0.0025) for snippets, 2 ($0.005) for page content (default, up to ~12,000 chars per result). `include_answer: true` adds an AI answer for +2 ($0.005). - **Fetch** (`POST /v1/fetch`): web pages and documents (PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, RTF, CSV) as clean markdown. Up to 10 URLs per call. 1 credit ($0.0025) per URL; failed URLs are free. - **Extract** (`POST /v1/extract`): fetch one page and answer a prompt about it with AI (a text answer, not JSON). 10 credits ($0.025). - **Research** (`POST /v1/research`): splits a question into sub-queries, reads many sources, returns a cited report. 50 credits ($0.125). Base URL: https://sofya.co MCP endpoint: https://mcp.sofya.co/mcp (Streamable HTTP; sign in with OAuth, or send the key header) Auth: `Authorization: Bearer sofya_live_...` or `X-API-Key: sofya_live_...` (create a key at https://sofya.co/dashboard, or have your user approve one for you: https://sofya.co/auth.md). Signing up with a GitHub account over a year old gives 2,000 free credits every 30 days; email sign-ups start at 0. Timeouts: give your HTTP client at least 90 s. Search with an AI answer, extract and research can take 5 to 60 s. Pricing: $0.0025 per credit, pay as you go, no subscription. Minimum top-up $10 (4,000 credits). Purchased credits never expire. An agent can make a payment link for its user with `POST /v1/billing/topup` and check credits with `GET /v1/billing/balance`. Both also return a `pay_url`, which an agent with a Machine Payments Protocol (MPP) wallet can pay itself, by card through a Link wallet or in USDC on Tempo. A wallet alone is not enough to start: you need a key first, which your user approves once. After that you can pay without them. Rate limit: 30 requests/second per API key (REST and MCP counted separately). ## Billing and errors - Only a 2xx response is charged, at exactly its `credits_used`. Any 4xx or 5xx costs nothing: credits reserved at the start are refunded automatically, timeouts included. Retrying after an error is safe. - Fetch: a URL that fails comes back as `success: false` inside a 200 and is refunded. A single URL gives up after 50s. - 400 bad request, 401 bad, revoked or expired key, or IP not in the key's allowlist, 402 out of credits (the body has a `top_up_url` to give your user and a `pay_url`) or the key hit its owner's limit (`key_cap_reached`), 422 invalid parameter or (extract) the target page couldn't be fetched, 429 rate limited (wait `Retry-After` seconds), 502 internal error (retry), 503 search capacity unavailable (retry shortly), 504 hit the 60s limit (55s for research). Over MCP, errors come back as a tool result with `isError: true`. ## Docs - [skill.md](https://sofya.co/skill.md): complete agent guide. Tool schemas for Claude and OpenAI, every parameter, example responses, error handling. - [docs.md](https://sofya.co/docs.md): the full API documentation as Markdown (also at [llms-full.txt](https://sofya.co/llms-full.txt)) - [API documentation](https://sofya.co/docs): full REST and MCP reference with examples - [OpenAPI schema](https://sofya.co/openapi.json): for client codegen - [auth.md](https://sofya.co/auth.md): how an agent gets a key (its user approves) and credits - [Pricing](https://sofya.co/pricing): credit costs, FAQ ## MCP setup [Setup for each app](https://sofya.co/docs#mcp): claude.ai, Claude Desktop, ChatGPT, Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI. - claude.ai / Claude Desktop / ChatGPT: add `https://mcp.sofya.co/mcp` as a custom connector and sign in with a Sofya account (OAuth, no key needed). - Claude Code: `claude mcp add --transport http sofya https://mcp.sofya.co/mcp` then `/mcp` to sign in, or add `--header "Authorization: Bearer sofya_live_..."`. - Tools: `search`, `fetch`, `extract`, `research` (read-only; same parameters and JSON as REST), plus `get_balance` and `buy_credits` (a payment link for the user). ## Optional - [GET /v1/status](https://sofya.co/v1/status): endpoint health and latency, no auth - [GET /v1/updates](https://sofya.co/v1/updates): product changelog, newest first, no auth - [Off-host status](https://status.sofya.co): watches the website from a separate server, so it stays up when Sofya is down. Feeds: https://status.sofya.co/api/v2/status.json (overall), https://status.sofya.co/api/v2/summary.json (Statuspage-compatible) - [Playground](https://sofya.co/playground): try the API in a browser - [Dashboard](https://sofya.co/dashboard): API keys, credits, usage