POST /v1/search

Web Search API for AI Agents and LLM Workflows

Run a query, get ranked results with titles, URLs, and snippets in one call.

Programmatic web search for AI apps and agents. Send a query, get back ranked results with titles, URLs, and snippets as structured JSON, ready to feed an LLM or chain into a scrape.

Try a live search

View API docs

How it works

Build it step by step.

The real flow, one step at a time. Switch between TypeScript, Python, and cURL on any snippet.

1
Send a query
POST a query string to /v1/search with an optional result limit and locale.
```
const results = await webclaw.search({  query: "best vector databases 2026",  limit: 10,});
```

Get ranked results

Receive a JSON array of results, each with a title, URL, and snippet, ordered by relevance.

// Each hit: { title, url, snippet }for (const hit of results.data) {  console.log(hit.title, hit.url);  console.log(hit.snippet);}

Feed or scrape

Pass the snippets into an LLM prompt, or take the top URLs and call /v1/scrape for full page content.

// Pull full content from the top resultconst top = results.data[0];const page = await webclaw.scrape({  url: top.url,  formats: ["markdown"],});console.log(page.markdown);

4
Log and reuse
Every query is recorded in the dashboard with its results, timing, and cost for replay and debugging.

Try a live search

Why webclaw

Built for web search.

Ranked results as structured JSON, no HTML parsing

One API for search-then-scrape: top URLs flow straight into /v1/scrape

Tunable result count and locale per query

Pairs with the MCP server so agents can search and read the web natively

Dashboard history logs every query with results, timing, and cost

What you get

Everything this use case needs.

Query-to-ranked-results in one call
Structured JSON: title, URL, snippet
Configurable result count and locale
Search-then-scrape with /v1/scrape
Available as an MCP tool for agents

Where it fits

Built for the messy parts.

LLMs are frozen at their training cutoff and have no built-in way to look things up. To answer a current question, your app needs live search results, but consumer search engines have no clean API, return HTML you have to scrape, and rate-limit aggressively. Building and maintaining your own SERP scraper is a tax on every feature that needs fresh information.

webclaw's /v1/search takes a query string and returns ranked results as structured JSON, each with title, URL, and snippet. Pass them straight into an LLM prompt, or take the top URLs and call /v1/scrape to pull the full page content. One endpoint replaces a fragile SERP scraper, and it pairs cleanly with the rest of the API for search-then-read agent loops.

Common questions

Frequently asked questions

What does the web search endpoint return?

A ranked list of results for your query as structured JSON. Each result includes a title, URL, and snippet, so you can feed them to an LLM or pick URLs to scrape without parsing any HTML.

Can I get the full page content of a search result?

Yes. Search returns the URLs, then call /v1/scrape on any of them to get clean markdown, JSON, or text. This search-then-read pattern is the standard way to give an agent live, citeable web context.

Can an AI agent use webclaw search directly?

Yes. Search is exposed as a tool on the webclaw MCP server and through the TypeScript, Python, and Go SDKs, so any MCP-compatible agent can run a query and act on the results in one step.

For AI agents

Or hand it to your agent.

Add the webclaw MCP server to Claude, Cursor, or any MCP client, then paste this prompt. The agent calls the webclaw tools and hands the result back to your model — no code to write.

PROMPT FOR YOUR AGENT

Using the webclaw tools, run a web search for [your search query] with the search tool and give the LLM live results to work with. Return the top 10 ranked hits as a table with columns for rank, title, URL, and snippet. Then take the top 3 URLs and call the scrape tool on each to pull the full page content as clean markdown. Read that content and write a short, synthesized answer to [the question you actually want answered], citing each claim with the source URL it came from. Flag any result whose snippet looks outdated or off-topic so I know to ignore it.

Set up the MCP server