> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchbean.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Curated tools: normalized search, read, and weather

> Call every fetchbean capability at its own POST /v1/<name> endpoint, including five provider-independent tools that always return the same JSON shape.

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.

<CardGroup cols={2}>
  <Card title="Search" icon="magnifying-glass" href="#search">
    **POST /v1/search** — web search with ranked results
  </Card>

  <Card title="Read" icon="book-open" href="#read">
    **POST /v1/read** — fetch any URL as clean markdown
  </Card>

  <Card title="Weather" icon="cloud-sun" href="#weather">
    **POST /v1/weather** — current weather by city or lat/lon
  </Card>

  <Card title="iOS App Search" icon="app-store-ios" href="#ios-app-search">
    **POST /v1/ios\_app\_search** — find iOS apps by name
  </Card>

  <Card title="Instagram User" icon="instagram" href="#instagram-user">
    **POST /v1/instagram\_user** — public Instagram profile *(beta)*
  </Card>
</CardGroup>

**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](/catalog), or under **Tools** in the API Reference tab; anything callable this way is equally callable through [`POST /v1/run`](/guides/raw-run).

<Note>
  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.
</Note>

***

## 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. |

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    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}'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    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);
    ```
  </Tab>
</Tabs>

**Normalized response shape**

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

```json theme={null}
{
  "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`. |

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://api.fetchbean.com/v1/read \
      -H "X-API-Key: $FETCHBEAN_KEY" \
      -H "Content-Type: application/json" \
      -d '{"url":"https://example.com/article"}'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    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);
    ```
  </Tab>
</Tabs>

***

## 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`.        |

<Tabs>
  <Tab title="curl — city name">
    ```bash theme={null}
    curl https://api.fetchbean.com/v1/weather \
      -H "X-API-Key: $FETCHBEAN_KEY" \
      -H "Content-Type: application/json" \
      -d '{"q":"San Francisco","units":"imperial"}'
    ```
  </Tab>

  <Tab title="curl — coordinates">
    ```bash theme={null}
    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"}'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    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);
    ```
  </Tab>
</Tabs>

***

## 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.                             |

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    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}'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    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);
    ```
  </Tab>
</Tabs>

***

## 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.        |

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

<Tabs>
  <Tab title="curl — by username">
    ```bash theme={null}
    curl https://api.fetchbean.com/v1/instagram_user \
      -H "X-API-Key: $FETCHBEAN_KEY" \
      -H "Content-Type: application/json" \
      -d '{"username":"nasa"}'
    ```
  </Tab>

  <Tab title="curl — by user ID">
    ```bash theme={null}
    curl https://api.fetchbean.com/v1/instagram_user \
      -H "X-API-Key: $FETCHBEAN_KEY" \
      -H "Content-Type: application/json" \
      -d '{"user_id":"528817151"}'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    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);
    ```
  </Tab>
</Tabs>

***

<Note>
  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](/guides/raw-run).
</Note>