Curated tools: normalized search, read, and weather

Curated tools are clean, normalized endpoints that sit on top of fetchbean’s provider network and always return the same JSON shape. Instead of dealing with different response formats from Exa, Jina, OpenWeather, or Tikhub, you call one predictable URL and get back a consistent structure every time. This makes curated tools the fastest way to add web search, page reading, weather, or social lookups to an AI 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

Instagram User

POST /v1/instagram_user — public Instagram profile (beta)

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 "Authorization: Bearer $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: {
    "Authorization": `Bearer ${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 "Authorization: Bearer $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: {
    "Authorization": `Bearer ${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 "Authorization: Bearer $FETCHBEAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"San Francisco","units":"imperial"}'

curl https://api.fetchbean.com/v1/weather \
  -H "Authorization: Bearer $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: {
    "Authorization": `Bearer ${process.env.FETCHBEAN_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ q: "San Francisco", units: "imperial" }),
});
const data = await res.json();
console.log(data);

Instagram User

POST /v1/instagram_user returns a public Instagram profile by username or user ID. Pass either username or user_id in the request body. Parameters

Parameter	Type	Required	Description
`username`	string	no	Instagram username, e.g. `"nasa"`. Required if `user_id` is not provided.
`user_id`	string	no	Instagram numeric user ID. Required if `username` is not provided.

Instagram User is in beta and is gated to organizations with beta access. Contact support if you need access enabled for your account.

curl — by username
curl — by user ID
Node.js

curl https://api.fetchbean.com/v1/instagram_user \
  -H "Authorization: Bearer $FETCHBEAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"nasa"}'

curl https://api.fetchbean.com/v1/instagram_user \
  -H "Authorization: Bearer $FETCHBEAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"528817151"}'

const res = await fetch("https://api.fetchbean.com/v1/instagram_user", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.FETCHBEAN_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ username: "nasa" }),
});
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.

Search

Read

Weather

Instagram User

​Search

​Read

​Weather

​Instagram User

Search

Read

Weather

Instagram User