API & MCP

Quickstart

A single GET request. No authentication.

curl 'https://freeserp.ai/api.php?q=ai+chatbot&size=3'

Returns ranked results as JSON — domain, title, LLM summary, Domain Rating, live date, tech stack and more.

Endpoint

Also reachable as /api. Read-only. Responses are cached ~30s at the edge.

Parameters

Param	Type	Default	Description
q	string	—	Full-text query. Matches title, AI summary and page text; exact domain names are boosted to the top. Omit q to browse/filter the whole index.
sort	enum	relevance	Any sortable field (see Sorting). relevance = text score × Domain Rating.
order	asc·desc	desc	Sort direction (ignored for relevance).
size	int	20	Results per page, 1–100.
from	int	0	Offset for paging (max 10,000).
all	0·1	0	1 also returns parked/empty domains. Default: real content sites only.
ai	0·1	0	1 restricts to AI-built sites (ai_source ∈ ai_likely, lovable, base44, v0, bolt).
content	0·1	0	1 also returns the full extracted page text of each result under content (not just the AI summary).
content_max	int	—	Cap the returned page text to N characters. Omit for the full text.
dr_min / dr_max	int	—	Domain Rating range filter (0–100).
from_date / to_date	date	—	Filter by went_live (YYYY-MM-DD).
Plus an exact-match filter for every keyword field — pass the field name as a query param:
category	keyword	—	e.g. ai, betting/casino
ai_source	keyword	—	e.g. shopify, nextjs, lovable
ai_categories	keyword	—	AI sub-niche, e.g. Image Generation
tld	keyword	—	e.g. ai, io
webserver	keyword	—	e.g. cloudflare, nginx
http_status	number	—	e.g. 200

Response

{
  "ok": true,
  "query": "ai chatbot",
  "total": 48213,
  "count": 3,
  "from": 0, "size": 3,
  "sort": "relevance", "order": "desc",
  "filters": { "real_site": "1" },
  "took_ms": 34, "engine_ms": 21,
  "results": [
    {
      "domain": "example.ai",
      "url": "https://example.ai",
      "title": "Example — AI chatbot for support",
      "ai_summary": "Example is an AI chatbot platform that …",
      "category": "ai",
      "ai_categories": ["AI Chatbot & Assistant"],
      "ai_source": "nextjs",
      "dr": 41, "went_live": "2026-08-22", "first_seen": "2026-07-10",
      "tld": "ai", "http_status": 200,
      "content_length": 8123, "html_size": 40213,
      "_score": 3182.4
    }
  ]
}

Sorting — every field

Pass any of these as sort=, with order=asc|desc:

All fields

Every field returned per result, and whether you can filter or sort on it.

Field	Type	Sort	Filter	Description
domain	keyword	✓	✓	Registered domain (e.g. example.com)
title	text	—	✓	Page <title>
ai_summary	text	—	✓	LLM-generated factual overview of the site
category	keyword	✓	✓	High-level category: 'ai', 'betting/casino', or null
ai_categories	keyword	✓	✓	AI sub-niche taxonomy (multi-valued)
ai_source	keyword	✓	✓	Builder / stack signal: wordpress, shopify, nextjs, lovable, v0, bolt, base44, ai_likely, not_ai…
dr	number	✓	✓	Domain Rating 0–100 (authority proxy)
went_live	date	✓	✓	Date the liveness probe first confirmed the site live
first_seen	date	✓	✓	Date the domain was first discovered
real_site	number	✓	✓	1 = real content site, 0 = parked/empty/error
tld	keyword	✓	✓	Top-level domain (com, ai, io…)
http_status	number	✓	✓	Last HTTP status of the homepage
content_length	number	✓	✓	Extracted text length (bytes)
html_size	number	✓	✓	Raw HTML size (bytes)
webserver	keyword	✓	✓	Server header (nginx, Apache, cloudflare…)
ip	ip	✓	✓	Resolved IP address
fetched_at	date	✓	—	When the HTML was last fetched

Examples

Newest AI sites, most authoritative first

curl 'https://freeserp.ai/api.php?ai=1&sort=dr&order=desc&size=10'

All sites built on Shopify, most authoritative first

curl 'https://freeserp.ai/api.php?ai_source=shopify&sort=dr&order=desc&size=25'

High-DR news sites that went live in the last two weeks

curl 'https://freeserp.ai/api.php?q=news&dr_min=30&from_date=2026-08-16&sort=went_live&order=desc'

Browse by niche, no text query

curl 'https://freeserp.ai/api.php?ai_categories=Image%20Generation&sort=dr&order=desc'

Return full page text, not just the summary

curl 'https://freeserp.ai/api.php?q=ai+chatbot&content=1&content_max=4000&size=3'

Identify yourself (optional)

There is no key and no signup — which also means that when something is about to change, we have no way to reach you. These four fields fix that. Every one is optional, nothing is validated, and none of them affect your results.

curl 'https://freeserp.ai/api.php?q=ai&agent=MyAgent/1.0&[email protected]&project=Acme&website=https://acme.com'

Field	Example	Purpose
agent	MyAgent/1.0	Your agent name + version (also accepted as the X-Agent header).
email	[email protected]	Contact address — contact= works the same. Used only to reach a human about this API.
project	Acme Research	The project/product making the calls.
website	https://acme.com	Project website.

Over MCP, pass the same fields as arguments to any freeserp_search call. Sending them once is enough. What it buys you: we can warn before a breaking change, ask what you are missing, and — if your traffic starts hurting the service — ask you to slow down instead of blocking you. Stored privately next to request counts; never published, never shared.

MCP connector

FreeSerp ships a hosted Streamable-HTTP MCP server — one URL, no install. Tools and their schemas are generated live from the field registry, so they never drift from the API.

A plain GET on that URL returns the live tool catalog (server, transport, tool_count, and every tool with its description) — same shape your client discovers over JSON-RPC:

curl 'https://freeserp.ai/mcp'

Add it to Claude (Desktop / Code / any MCP client)

Point the client at the remote endpoint via mcp-remote:

{
  "mcpServers": {
    "freeserp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://freeserp.ai/mcp"]
    }
  }
}

Restart the client — your agent now has freeserp_search, freeserp_list_endpoints and freeserp_get.

Raw JSON-RPC

Talk to it directly — initialize, then tools/list / tools/call:

# discover tools
curl -s 'https://freeserp.ai/mcp' -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# run a search
curl -s 'https://freeserp.ai/mcp' -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
        "name":"freeserp_search",
        "arguments":{"q":"ai chatbot","sort":"dr","order":"desc","size":5}}}'