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

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

Named provider tools are the other 465 endpoints — one per capability in the catalog, named provider_action (for example POST /v1/linear_issues or POST /v1/stripe_charges). These pass straight through to that specific provider, so the shape is the provider’s own. Browse them all in the catalog, or under Tools in the API Reference tab; anything callable this way is equally callable through POST /v1/run.

Pick a provider-independent tool when you want a shape that won’t move. Pick a named provider tool, or run, when you want that provider’s exact 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);

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 "X-API-Key: $FETCHBEAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"nasa"}'

curl https://api.fetchbean.com/v1/instagram_user \
  -H "X-API-Key: $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: {
    "X-API-Key": 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.

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

Instagram User

Search

Read

Weather

iOS App Search

Instagram User

​Search

​Read

​Weather

​iOS App Search

​Instagram User

Search

Read

Weather

iOS App Search

Instagram User