Ferret API Reference

Web search engine for AI agents — Open source alternative to Tavily Version 0.6.0 — 333 parsers, 363 routes, 121 MCP tools, 17 business endpoints

Overview

Base URL: http://localhost:9093

Quickstart

Installation

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

# Start the REST API
./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"])

Core Endpoints

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:

Response:

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

Available search engines (18+): /search/bing, /search/ddg, /search/brave, /search/google, /search/yandex, /search/yahoo, /search/aol, /search/seznam, /search/baidu, /search/qwant, /search/startpage, /search/dogpile, /search/you, /search/ask, /search/rambler

2. Extract

Extract clean content from one or more URLs (Tavily-compatible format):

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

Parameters:

Response (Tavily-compatible):

{
  "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"

Tavily-compatible crawl:

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

Response (Tavily-compatible):

{
  "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 (Tavily-style):

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

Parameters:

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"
}

6. Batch

Run multiple parsers in one request:

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

Business Endpoints

Ferret ships 17 business endpoints that aggregate multiple parsers into cross-cutting analyses. Each one has a paired /llm route returning an LLM-ready markdown prompt (~800 tokens). Full detail on the Business Endpoints page.

LLM routes

Each business endpoint has a /llm variant that returns an LLM-ready markdown prompt (~800 tokens), designed for direct injection into a chat completion:

# Structured JSON analysis
curl "http://localhost:9093/seo/audit?q=example.com"

# LLM-ready markdown prompt
curl "http://localhost:9093/seo/audit/llm?q=example.com"

There are 16 /llm routes in total. See Business Endpoints for request/response examples.

Export Formats

Every endpoint supports the ?format= query parameter. See Export Formats for full examples.

curl "http://localhost:9093/search/bing?q=rust&format=csv"

Search Engines

Ferret supports 18+ search engines, each available at /search/<engine>:

The aggregate /search endpoint fans out across all engines, deduplicates by URL, scores, and ranks.

Rate Limits

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

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")

See the Python SDK page for the full method list.

JavaScript

npm install ferret-client

import { FerretClient } from 'ferret-client';

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

See the JavaScript SDK page.

LangChain

from langchain_ferret import FerretSearchTool, FerretResearchTool

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

See LangChain Integration.

MCP Server

Ferret exposes a Model Context Protocol (MCP) server on port 9094 with 121 tools, compatible with Cursor, Claude Desktop, Claude Code, and OpenAI. See the MCP Server page for full configuration.

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