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

# Call any fetchbean provider directly with POST /v1/run

> Route requests to any fetchbean-supported provider and get back its native response — no per-provider SDK, account, or API key required.

`POST /v1/run` is the complete surface of fetchbean. It lets you reach any supported provider endpoint directly and returns the provider's native response without any normalization or transformation. Every [curated tool](/guides/curated-tools) is built on top of this same endpoint, so anything you can do with a curated tool you can also do — and more — with `/v1/run`.

## Request format

Every `/v1/run` call takes three fields in the request body:

| Field      | Type   | Description                                                                |
| ---------- | ------ | -------------------------------------------------------------------------- |
| `provider` | string | The provider id — for example `exa`, `tavily`, `jina`, or `openweather`.   |
| `endpoint` | string | The provider's own endpoint path — for example `/search` or `/v1/extract`. |
| `input`    | object | The request body passed through directly to the provider.                  |

## Examples

<CodeGroup>
  ```bash Exa — neural web search theme={null}
  curl https://api.fetchbean.com/v1/run \
    -H "X-API-Key: $FETCHBEAN_KEY" \
    -H "Content-Type: application/json" \
    -d '{"provider":"exa","endpoint":"/search","input":{"query":"best vector databases","numResults":10}}'
  ```

  ```bash Jina — page reader theme={null}
  curl https://api.fetchbean.com/v1/run \
    -H "X-API-Key: $FETCHBEAN_KEY" \
    -H "Content-Type: application/json" \
    -d '{"provider":"jina","endpoint":"/read","input":{"url":"https://example.com/post"}}'
  ```

  ```bash Tavily — agent-focused search theme={null}
  curl https://api.fetchbean.com/v1/run \
    -H "X-API-Key: $FETCHBEAN_KEY" \
    -H "Content-Type: application/json" \
    -d '{"provider":"tavily","endpoint":"/search","input":{"query":"AI agent frameworks","include_answer":true}}'
  ```

  ```bash Perplexity — synthesized answers theme={null}
  curl https://api.fetchbean.com/v1/run \
    -H "X-API-Key: $FETCHBEAN_KEY" \
    -H "Content-Type: application/json" \
    -d '{"provider":"perplexity","endpoint":"/search","input":{"query":"What is RAG?","max_results":5}}'
  ```

  ```bash Parallel — multi-query search theme={null}
  curl https://api.fetchbean.com/v1/run \
    -H "X-API-Key: $FETCHBEAN_KEY" \
    -H "Content-Type: application/json" \
    -d '{"provider":"parallel","endpoint":"/v1/search","input":{"search_queries":["vector databases","embedding models"]}}'
  ```

  ```bash Parallel — URL extraction theme={null}
  curl https://api.fetchbean.com/v1/run \
    -H "X-API-Key: $FETCHBEAN_KEY" \
    -H "Content-Type: application/json" \
    -d '{"provider":"parallel","endpoint":"/v1/extract","input":{"urls":["https://example.com"]}}'
  ```
</CodeGroup>

## Finding a provider and endpoint

The provider list grows continuously, so rather than reproduce it here, look it up where it stays current:

<CardGroup cols={2}>
  <Card title="Catalog" icon="book" href="/catalog">
    Every provider and endpoint, with parameters, credit cost, and a ready-to-run curl example.
  </Card>

  <Card title="Connections" icon="key" href="/connections">
    The providers that run on your own account, and what each needs to connect.
  </Card>
</CardGroup>

Both pages are generated from the live registry, so they never fall behind what the API actually serves.

<Tip>
  Not sure which provider or endpoint to use? Call `GET /discover?q=your+task` — it is public, needs no key, and returns a ranked list of methods matching your task, each with the exact `provider` and `endpoint` to pass to `run`.
</Tip>

## Providers that need your own account

Most providers run on credentials fetchbean manages, so your key is all you need. Some act on **your** account and must be connected first — `discover` flags these, and a `run` against an unconnected provider fails with `credential_required` and is billed zero. See [Connections](/connections).