Curated tools: normalized search, read, and weather

Every capability in the fetchbean catalog has its own endpoint at POST /v1/<name>, so you can call a tool by name instead of assembling a provider and endpoint pair. There are two kinds. Provider-independent tools are the five below. Each one is backed by a provider fetchbean chooses, and each returns a normalized JSON shape that stays stable even if the provider behind it changes. These are the fastest way to add web search, page reading, weather, or app lookups to an agent.

Search

POST /v1/search — web search with ranked results

Read

POST /v1/read — fetch any URL as clean markdown

Weather

POST /v1/weather — current weather by city or lat/lon

iOS App Search

POST /v1/ios_app_search — find iOS apps by name

Instagram User

Named provider tools are registered operations named provider_action (for example POST /v1/linear_issues or POST /v1/stripe_charges). Their responses use that operation’s provider-specific shape. Browse them in the catalog, or under Tools in the API Reference tab. Each named tool is also callable through POST /v1/run.

Pick a provider-independent tool when you want a normalized shape. Pick a named provider tool, or run, when you want the registered operation’s provider-specific response.

Search

POST /v1/search runs a web search and returns a ranked list of results with titles, URLs, and snippets. It is backed by fetchbean’s search provider network so you do not need to pick or configure a specific search engine. Parameters

Parameter	Type	Required	Description
`query`	string	yes	The search query.
`max_results`	integer	no	Maximum number of results to return.

curl
Node.js

curl https://api.fetchbean.com/v1/search \
  -H "X-API-Key: $FETCHBEAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"best vector databases","max_results":5}'

const res = await fetch("https://api.fetchbean.com/v1/search", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.FETCHBEAN_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "best vector databases", max_results: 5 }),
});
const data = await res.json();
console.log(data.results);

Normalized response shape Every /v1/search response follows this exact structure regardless of which underlying search provider is used:

{
  "results": [
    { "title": "Qdrant", "url": "https://qdrant.tech", "snippet": "High-performance vector search..." },
    { "title": "Weaviate", "url": "https://weaviate.io", "snippet": "Open-source vector database..." }
  ]
}

Read

POST /v1/read fetches any public URL and returns the page content as clean, LLM-ready markdown. Navigation, ads, and other clutter are stripped automatically. Parameters

Parameter	Type	Required	Description
`url`	string	yes	The public URL to fetch.
`format`	string	no	Output format hint, e.g. `markdown`.

curl
Node.js

curl https://api.fetchbean.com/v1/read \
  -H "X-API-Key: $FETCHBEAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

const res = await fetch("https://api.fetchbean.com/v1/read", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.FETCHBEAN_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com/article" }),
});
const data = await res.json();
console.log(data.content);

Weather

POST /v1/weather returns current weather conditions for a location. Pass a city name as q, or use lat and lon for coordinate-based lookups. Use units to control whether temperatures are returned in metric, imperial, or standard units. Parameters

Parameter	Type	Required	Description
`q`	string	no	City name, e.g. `"San Francisco"`. Required if `lat`/`lon` are not provided.
`lat`	number	no	Latitude. Use with `lon`.
`lon`	number	no	Longitude. Use with `lat`.
`units`	string	no	`metric`, `imperial`, or `standard` (Kelvin). Defaults to `standard`.

curl — city name
curl — coordinates
Node.js

curl https://api.fetchbean.com/v1/weather \
  -H "X-API-Key: $FETCHBEAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"San Francisco","units":"imperial"}'

curl https://api.fetchbean.com/v1/weather \
  -H "X-API-Key: $FETCHBEAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat":37.7749,"lon":-122.4194,"units":"metric"}'

const res = await fetch("https://api.fetchbean.com/v1/weather", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.FETCHBEAN_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ q: "San Francisco", units: "imperial" }),
});
const data = await res.json();
console.log(data);

iOS App Search

POST /v1/ios_app_search finds iOS apps by name and returns their App Store listings. Use it to resolve an app name to the identifiers other app-intelligence tools take. Parameters

Parameter	Type	Required	Description
`query`	string	yes	The app name or search terms.
`country`	string	no	Two-letter store country code, e.g. `us`.
`limit`	integer	no	1–50 results.

curl
Node.js

curl https://api.fetchbean.com/v1/ios_app_search \
  -H "X-API-Key: $FETCHBEAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"notion","country":"us","limit":5}'

const res = await fetch("https://api.fetchbean.com/v1/ios_app_search", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.FETCHBEAN_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "notion", country: "us", limit: 5 }),
});
const data = await res.json();
console.log(data);

For long-tail provider calls or providers not covered by curated tools, use POST /v1/run instead. It gives you direct access to every provider and method in the fetchbean catalog. See the Raw Run guide.

Get Started

Core Concepts

Guides

Reference

Curated tools: normalized search, read, and weather

Search

Read

Weather

iOS App Search

Instagram User

Search

Read

Weather

iOS App Search

Search

Read

Weather

iOS App Search

Instagram User

​Search

​Read

​Weather

​iOS App Search

Search

Read

Weather

iOS App Search