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

# search

> Find API providers by describing what you need in natural language.

The `search` tool finds paid API services that match a natural-language query. It returns ranked origins along with endpoint details and pricing, so you can call the best match immediately via [`fetch`](/tools/fetch).

Equivalent CLI command: `npx agentcash search <query>`

## When to use

Use `search` when you don't already know which origin to call. If the task clearly maps to a registered origin (people research → StableEnrich, image generation → StableStudio, social data → StableSocial, and so on), skip `search` and call [`discover_api_endpoints`](/tools/discover-api-endpoints) on that origin directly.

`search` is for discovering capabilities outside the registered origins.

## Parameters

<ParamField body="query" type="string" required>
  Natural-language description of what you need. Examples: `"send physical mail"`, `"generate music"`, `"flight prices"`, `"company financials"`.
</ParamField>

## Response

<ResponseField name="query" type="string">
  The original query, echoed back.
</ResponseField>

<ResponseField name="results" type="object[]">
  Ranked origins. The top result's `endpoint` includes the full input/output schema so it can be called without an extra `check_endpoint_schema` round-trip.

  <Expandable>
    <ResponseField name="origin" type="string">Origin URL.</ResponseField>
    <ResponseField name="title" type="string">Human-readable name.</ResponseField>
    <ResponseField name="description" type="string">What the origin offers.</ResponseField>
    <ResponseField name="favicon" type="string">Favicon URL.</ResponseField>
    <ResponseField name="protocols" type="string[]">Payment protocols the origin supports (e.g., `x402`, `mpp`).</ResponseField>

    <ResponseField name="endpoint" type="object">
      Best-matching endpoint for the query, when one exists.

      <Expandable>
        <ResponseField name="method" type="string">HTTP method.</ResponseField>
        <ResponseField name="path" type="string">Endpoint path.</ResponseField>
        <ResponseField name="summary" type="string">What the endpoint does.</ResponseField>
        <ResponseField name="authMode" type="string">`paid` or `siwx`.</ResponseField>
        <ResponseField name="price" type="string">Cost in USDC.</ResponseField>
        <ResponseField name="inputSchema" type="object">Request body schema.</ResponseField>
        <ResponseField name="outputSchema" type="object">Response schema.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Behavior

1. Sends the query to the AgentCash search index
2. Returns a ranked list of origins and their most relevant endpoints
3. The top result is pre-loaded with schema details so you can go straight to `fetch`

## Example

Ask your agent:

> Use AgentCash to search for an API that can send a physical postcard.

The agent calls `search`, picks the best matching origin, and then calls `fetch` on the endpoint it returned.