# Sofya

> Web search, fetch, extract, and research API for AI agents. One API key, four tools, clean markdown output.

Sofya gives AI agents four web tools via REST API and MCP:

- **Search**: Web search returning full page content, not just snippets. 1-10 credits.
- **Fetch**: Convert any URL to clean markdown. Supports pages, PDFs, DOCX. 1 credit.
- **Extract**: AI-powered structured data extraction from any page. 5 credits.
- **Research**: Multi-source deep research with AI synthesis and citations. 25 credits.

Base URL: https://sofya.yusufgurdogan.com
MCP endpoint: https://mcp.sofya.yusufgurdogan.com/mcp
Rate limit: 1 request/second per API key.

## Docs

- [API Documentation](https://sofya.yusufgurdogan.com/docs): Full REST API reference with examples
- [SKILL.md](https://sofya.yusufgurdogan.com/SKILL.md): AI-readable skill file with complete tool definitions and examples
- [Pricing](https://sofya.yusufgurdogan.com/pricing): Credit costs, plans, and FAQ

## Endpoints

- [POST /v1/search](https://sofya.yusufgurdogan.com/docs#search): Search the web. Returns extracted page content. 1-10 credits depending on depth (snippets/basic/advanced). Add include_answer for AI synthesis (+5 credits).
- [POST /v1/fetch](https://sofya.yusufgurdogan.com/docs#fetch): Fetch any URL as clean markdown. 1 credit.
- [POST /v1/extract](https://sofya.yusufgurdogan.com/docs#extract): Fetch a page and extract specific info with AI. 5 credits.
- [POST /v1/research](https://sofya.yusufgurdogan.com/docs#research): Deep research on a topic. Decomposes query, searches multiple sources, synthesizes report with citations. 25 credits.

## MCP Setup

- [Claude Code](https://sofya.yusufgurdogan.com/docs#mcp): `claude mcp add --transport http sofya https://mcp.sofya.yusufgurdogan.com/mcp --header "Authorization: Bearer ay_live_..."`
- [Cursor](https://sofya.yusufgurdogan.com/docs#mcp): Add to ~/.cursor/mcp.json
- [Codex](https://sofya.yusufgurdogan.com/docs#mcp): Add to ~/.codex/config.toml
- [Windsurf](https://sofya.yusufgurdogan.com/docs#mcp): Add to ~/.codeium/windsurf/mcp_config.json
- [VS Code Copilot](https://sofya.yusufgurdogan.com/docs#mcp): Add to .vscode/mcp.json

## Optional

- [Dashboard](https://sofya.yusufgurdogan.com/dashboard): Manage API key, credits, and usage
- [Playground](https://sofya.yusufgurdogan.com/playground): Try the API live in your browser
- [Status](https://sofya.yusufgurdogan.com/status): Real-time API health and latency