# Quercle

> AI-powered web fetching and search API. Fetch content from any URL, perform web searches, and get AI-synthesized answers with source citations.

## About

Quercle provides five core endpoints for agent web workflows:

- **Fetch** (`/v1/fetch`): Fetch a URL and return an AI-synthesized answer based on page content and your prompt.
- **Search** (`/v1/search`): Search the web and return an AI-synthesized answer from the retrieved results.
- **Raw Fetch** (`/v1/raw_fetch`): Fetch a URL and return raw markdown or HTML.
- **Raw Search** (`/v1/raw_search`): Run web search and return raw results.
- **Extract** (`/v1/extract`): Fetch a URL and return chunks relevant to a query.

## Getting Started

1. Sign up at https://quercle.dev/sign-up
2. Create an API key in https://quercle.dev/dashboard
3. Test requests in https://quercle.dev/playground
4. Go to docs at https://quercle.dev/docs

## API Reference

Base URL: https://api.quercle.dev

### /v1/fetch

Fetch a URL and return an AI-synthesized answer based on page content and your prompt.

Parameters:
- url (string, required): The URL to fetch and analyze.
- prompt (string, required): Instructions for how to analyze the page content. Be specific about what information you want to extract.

Response fields:
- result (string, required)

### /v1/search

Search the web and return an AI-synthesized answer from the retrieved results.

Parameters:
- query (string, required): The search query to find information about. Be specific.
- allowed_domains (string[], optional): Only include results from these domains (e.g., ['example.com', 'docs.example.org']).
- blocked_domains (string[], optional): Exclude results from these domains (e.g., ['example.com', 'docs.example.org']).

Note: allowed_domains and blocked_domains cannot be used together.

Response fields:
- result (string, required)

### /v1/raw_fetch

Fetch a URL and return raw markdown or HTML.

Parameters:
- url (string, required): The URL to fetch.
- format ("markdown" | "html", optional): Output format for fetched content. Defaults to `markdown`.
- use_safeguard (boolean, optional): Enable prompt-injection detection when `format` is `markdown`.

Note: use_safeguard=true is not supported when format=html.

Response fields:
- result (string, required)
- unsafe (boolean, optional)

### /v1/raw_search

Run web search and return raw results.

Parameters:
- query (string, required): The search query to run against the web.
- format ("markdown" | "json", optional): Output format for search results. Defaults to `markdown`.
- use_safeguard (boolean, optional): Enable prompt-injection detection on search results.

Response fields:
- result (string | { title: string; url: string; content: string }[], required)
- unsafe (boolean, optional)

### /v1/extract

Fetch a URL and return chunks relevant to a query.

Parameters:
- url (string, required): The URL to fetch and extract relevant chunks from.
- query (string, required): What information to extract from the page content.
- format ("markdown" | "json", optional): Output format for extracted chunks. Defaults to `markdown`.
- use_safeguard (boolean, optional): Enable prompt-injection detection on selected extracted content.

Response fields:
- result (string | string[], required)
- unsafe (boolean, optional)

## Authentication

All requests require a Bearer token:
```
Authorization: Bearer qk_your_api_key
```

## Quick Examples

### Python

```python
from quercle import QuercleClient

client = QuercleClient(api_key="qk_your_api_key")
response = client.fetch("https://example.com", "Summarize the main points")
print(response.result)
```

### TypeScript

```typescript
import { quercle } from "@quercle/sdk";

const client = quercle({ apiKey: "qk_your_api_key" });
const response = await client.search("latest AI developments");
console.log(response.result);
```

## SDKs

- SDK: `uv add quercle` ([GitHub](https://github.com/quercledev/quercle-python))
- TypeScript: `bun add @quercle/sdk` ([GitHub](https://github.com/quercledev/quercle-js))
- LangChain: `uv add langchain-quercle` ([GitHub](https://github.com/quercledev/langchain-quercle))
- CrewAI: `uv add quercle-crewai` ([GitHub](https://github.com/quercledev/quercle-crewai))
- LlamaIndex: `uv add llama-index-tools-quercle` ([GitHub](https://github.com/quercledev/quercle-llama-index))
- Pydantic AI: `uv add quercle-pydantic-ai` ([GitHub](https://github.com/quercledev/quercle-pydantic-ai))
- Google ADK: `uv add google-adk-quercle` ([GitHub](https://github.com/quercledev/google-adk-quercle))
- Vercel AI SDK: `bun add @quercle/ai-sdk` ([GitHub](https://github.com/quercledev/quercle-ai-sdk))
- MCP: `bunx @quercle/mcp` ([GitHub](https://github.com/quercledev/quercle-mcp))

## Links

- Docs: https://quercle.dev/docs
- Pricing: https://quercle.dev/#pricing
- GitHub: https://github.com/quercledev