Call registered provider operations with POST /v1/run

POST /v1/run executes operations registered in the fetchbean catalog. You identify an operation by its provider and endpoint, and fetchbean validates input against that operation’s schema before calling it. The result keeps the operation’s provider-specific shape instead of applying the normalized shape used by provider-independent tools. /v1/run does not accept arbitrary upstream URLs or undocumented provider methods. Use GET /discover, the catalog, or the OpenAPI specification to find registered operations and their input schemas.

Request format

The request body accepts these fields. provider and endpoint are required; input defaults to an empty object.

Field	Type	Description
`provider`	string	The provider id — for example `exa`, `tavily`, `jina`, or `openweather`.
`endpoint`	string	The endpoint coordinate registered for the operation, for example `/search` or `/v1/extract`.
`input`	object	Input validated against the registered operation’s JSON Schema.

Examples

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}}'

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"}}'

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}}'

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}}'

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"]}}'

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"]}}'

Finding an operation

Use the current catalog and connection reference:

Catalog

Every registered operation, with parameters, credit cost, and a ready-to-run curl example.

Connections

The providers that run on your own account, and what each needs to connect.

Not sure which operation to use? Call GET /discover?q=your+task. It is public, needs no key, and returns ranked matches with the provider and endpoint to pass to run.

Providers that need your own account

Managed operations use credentials fetchbean supplies. Operations that act on your account require a connection first. discover flags these, and a run against an unconnected provider fails with credential_required and is billed zero. See Connections.

Get Started

Core Concepts

Guides

Reference

Call registered provider operations with POST /v1/run

Request format

Examples

Finding an operation

Catalog

Connections

Providers that need your own account

​Request format

​Examples

​Finding an operation

Catalog

Connections

​Providers that need your own account

Request format

Examples

Finding an operation

Providers that need your own account