Ferret API Reference

Web search engine for AI agents — Open source, production-ready API Version 0.21 — 313+ parsers, 300+ routes

Quickstart

Installation

# Clone and build
git clone https://github.com/duan78/ferret.git
cd ferret
cargo build --release

# Start the server
./target/release/ferret serve
# → http://localhost:9093

# Or start MCP server
./target/release/ferret mcp --port 9094
# → http://localhost:9094/mcp

Your first search

curl -X POST http://localhost:9093/research \
  -H "Content-Type: application/json" \
  -d '{"query": "AI developments 2026"}'

Python SDK

from ferret import FerretClient

client = FerretClient("http://localhost:9093")

# Search
results = client.search("Who is Leo Messi?")
print(results)

# Research (multi-engine + summary)
report = client.research("AI developments 2026")
print(report["answer"])

# Extract
content = client.extract("https://example.com")
print(content["raw_content"])

API Reference

Base URL: http://localhost:9093

1. Search

Single search engine:

curl "http://localhost:9093/search/bing?q=web+scraping"

Multi-engine aggregate:

curl "http://localhost:9093/search?q=web+scraping"

Parameters:

Param	Type	Default	Description
`q`	string	—	Search query (required)
`pagecount`	int	5	Number of result pages
`no_cache`	bool	false	Bypass cache
`format`	string	json	Output format (`json` or `csv`)

Response:

{
  "success": true,
  "items": [
    {
      "title": "Result Title",
      "url": "https://...",
      "snippet": "Description...",
      "source": "bing"
    }
  ],
  "time_ms": 123
}

Available search engines: /search/bing, /search/ddg, /search/brave, /search/yahoo, /search/aol, /search/seznam, /search/baidu, /search/rambler, /search/qwant, /search/startpage, /search/dogpile, /search/you, /search/google

2. Extract

Extract clean content from one or more URLs:

curl "http://localhost:9093/extract?q=https://example.com&include_images=true"

Parameters:

Param	Type	Default	Description
`q`	string	—	URL to extract (required)
`include_images`	bool	false	Include page images
`include_raw_content`	bool	true	Return raw text content

Response:

{
  "results": [
    {
      "url": "https://example.com",
      "raw_content": "Page content as plain text...",
      "images": [],
      "favicon": "https://example.com/favicon.ico"
    }
  ],
  "failed_results": [],
  "response_time": "0.02"
}

3. Crawl

Crawl an entire website:

curl "http://localhost:9093/crawl?q=https://docs.ferret.guru"

Crawl multiple URLs:

curl "http://localhost:9093/crawl/v1?q=https://docs.ferret.guru"

Response:

{
  "base_url": "docs.ferret.guru",
  "results": [
    {
      "url": "https://docs.ferret.guru/page",
      "raw_content": "...",
      "favicon": "https://docs.ferret.guru/favicon.ico"
    }
  ],
  "failed_results": [],
  "response_time": "1.23"
}

4. Map

Discover all URLs on a domain without extracting content:

curl "http://localhost:9093/map?q=https://example.com"

Response:

{
  "urls": [
    "https://example.com",
    "https://example.com/about",
    "https://example.com/contact"
  ],
  "total": 3,
  "response_time": "0.35"
}

5. Research

Deep research: multi-engine search with aggregated results and summary:

curl -X POST http://localhost:9093/research \
  -H "Content-Type: application/json" \
  -d '{"query": "AI developments 2026", "max_results": 20}'

Parameters:

Param	Type	Default	Description
`query`	string	—	Research topic (required)
`max_results`	int	20	Max results to return
`model`	string	mini	`mini` (fast) or `pro` (deep)
`stream`	bool	false	SSE streaming

Response:

{
  "query": "AI developments 2026",
  "answer": "Summary of findings from 5 search engines...",
  "results": [
    {
      "title": "Article Title",
      "url": "https://...",
      "content": "Snippet...",
      "score": 0.95,
      "source": "bing"
    }
  ],
  "usage": {"searches": 5, "results_total": 42},
  "response_time": "2.34"
}

SDKs

Python

pip install ferret-client

from ferret import FerretClient

client = FerretClient("http://localhost:9093")

# Search
client.search("rust programming", engine="bing")

# Multi-search
client.search_all("rust programming")

# Extract
client.extract("https://example.com")

# Research
client.research("AI 2026")

# Crawl
client.crawl("https://docs.ferret.guru")

JavaScript

npm install ferret-client

import { FerretClient } from 'ferret-client';

const client = new FerretClient('http://localhost:9093');
const results = await client.search('web scraping');

LangChain

from langchain_ferret import FerretSearchTool, FerretResearchTool

tools = [
    FerretSearchTool(),
    FerretResearchTool(),
]

See LangChain Integration.

MCP Server

Ferret exposes a Model Context Protocol (MCP) server compatible with Cursor, Claude Desktop, Claude Code, and OpenAI.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "ferret-remote": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:9094/mcp"],
      "env": {}
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "ferret-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:9094/mcp"],
      "env": {}
    }
  }
}

Claude Code

claude mcp add ferret --transport http http://localhost:9094/mcp

Available MCP Tools

Tool	Description
`web_search`	Search the web (multi-engine)
`web_extract`	Extract content from URLs
`web_crawl`	Crawl a website
`web_research`	Deep research with summary
`web_suggest`	Search suggestions
`web_images`	Image search
`web_position`	SEO position check
`web_whois`	Domain WHOIS lookup
`web_cms`	CMS detection
+180 more tools	French data, finance, crypto…

Rate Limits

Ferret is self-hosted — there are no rate limits. Your infrastructure, your rules.

Environment	RPM
Development	Unlimited
Production	Unlimited
Crawl	Unlimited
Research	Unlimited

Best Practices

Optimize performance

# Use cache
curl "http://localhost:9093/search/bing?q=rust&no_cache=false"

# Limit results
curl "http://localhost:9093/search/bing?q=rust&pagecount=1"

# Batch multiple queries
curl -X POST http://localhost:9093/batch \
  -H "Content-Type: application/json" \
  -d '[
    {"parser": "bing", "query": "rust"},
    {"parser": "ddg", "query": "web scraping"}
  ]'

Error handling

All endpoints return {"success": true/false, "error": "..."} on failure.

Support

GitHub: github.com/duan78/ferret
Issues: github.com/duan78/ferret/issues
Self-hosted: your own infrastructure