# Web research API

Reference for Munition's web research routes, Exa, Firecrawl and Serper search and page reading: routes, input, output, price and limits.

Ten operations from three providers: Exa (neural search, page contents, similar pages, cited answers), Firecrawl (pages rendered with JavaScript, and web search) and Serper (Google web, news, images and shopping). Each one is sold three ways at one price: an x402 route, its MPP mirror under `/v1/mpp/`, and an MCP tool paid from the [account balance](/docs/payments#account-balance-current). The MPP route and the MCP tool take the same input and return the same result as the x402 route.

## How these routes work

- **One request, one price.** Every route is a `POST` with a JSON body and a JSON result, at a fixed price per call whatever the number of results. The tables below give each route, its tool id in `GET /v1/tools/prices` and its price in USDC.
- **Invalid input is never charged.** An unpaid request gets its challenge (`402`) before the body is read, on the x402 and MPP routes. A request with a payment and an invalid body gets `400 invalid_input` before the payment is verified.
- **Timeouts.** Munition waits up to 25 seconds for Exa and Serper and 28 seconds for Firecrawl.
- **Extra fields.** Result items can carry more fields from the provider than the tables list.
- **Failures after payment** keep the payment and return `422` or `502 upstream_failed` with `paidCallId`. Send the same request again with the same `Idempotency-Key` to call the provider again without a second charge: see [Errors and refunds](/docs/payments/errors#when-payment-settles-but-the-service-fails).

## Exa

### Search

Neural web search: up to 25 ranked results, with page contents in the same call if you ask for them.

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/exa/search` | `exa_search_direct` | 0.01 |
| MPP | `POST /v1/mpp/exa/search` | `exa_search_mpp` | 0.01 |
| Account balance | MCP tool `web_search` | `exa_search` | 0.01 |

Body of `POST /v1/exa/search`:

| Field | Type | Required | Default | Limits and notes |
| --- | --- | --- | --- | --- |
| `query` | string | yes | — | 1 to 2,000 characters, in natural language, not counting spaces at either end. |
| `numResults` | integer | no | 10 | 1 to 25. |
| `type` | string | no | auto | `auto`, `neural`, `keyword` or `fast`. |
| `category` | string | no | — | `company`, `research paper`, `news`, `pdf`, `github`, `tweet`, `personal site`, `linkedin profile`, `financial report` or `people`. |
| `includeDomains` | array of strings | no | — | Up to 50 domains to search in. |
| `excludeDomains` | array of strings | no | — | Up to 50 domains to leave out. |
| `startPublishedDate` | string | no | — | An ISO 8601 date or date-time (`2026-01-31` or `2026-01-31T00:00:00Z`), passed to Exa as the earliest publication date. Anything else is refused with `400` before payment. |
| `endPublishedDate` | string | no | — | An ISO 8601 date or date-time, passed to Exa as the latest publication date. Anything else is refused with `400` before payment. |
| `contents` | object | no | — | The page contents to include in each result, below. Omit it for metadata only. |

The `contents` object of `POST /v1/exa/search` and `POST /v1/exa/find-similar`:

| Field | Type | Required | Default | Limits and notes |
| --- | --- | --- | --- | --- |
| `text` | boolean or object | no | — | `true` for the page text, or an object with `maxCharacters` (up to 50,000). |
| `highlights` | boolean or object | no | — | `true`, or an object with `numSentences` (up to 20) and `highlightsPerUrl` (up to 10). |
| `summary` | boolean or object | no | — | `true`, or an object with a `query` (up to 500 characters) to focus the summary. |

Response of `POST /v1/exa/search`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `query` | string | yes | The query you sent. |
| `results` | array of objects | yes | Each result has `url`, and when known `title`, `publishedDate`, `author` and `score`, plus `text`, `highlights` and `summary` when `contents` asked for them. |
| `searchType` | string | no | The search type Exa used. |
| `meta` | object | yes | `resultCount` and `searchedAt`. |

### Page contents

The clean text of up to 20 known URLs from Exa's index, with a live crawl when needed. The cheapest way to read many pages.

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/exa/contents` | `exa_contents_direct` | 0.002 |
| MPP | `POST /v1/mpp/exa/contents` | `exa_contents_mpp` | 0.002 |
| Account balance | MCP tool `web_contents` | `exa_contents` | 0.002 |

Body of `POST /v1/exa/contents`:

| Field | Type | Required | Default | Limits and notes |
| --- | --- | --- | --- | --- |
| `urls` | array of strings | yes | — | 1 to 20 URLs. |
| `text` | boolean or object | no | true | `true`, `false`, or an object with `maxCharacters` (up to 50,000). |
| `highlights` | boolean or object | no | — | `true`, or an object with `numSentences` (up to 20). |
| `summary` | boolean or object | no | — | `true`, or an object with a `query` (up to 500 characters). |
| `livecrawl` | string | no | — | `never`, `fallback` or `always`: when Exa crawls the page live instead of using its index. |

Response of `POST /v1/exa/contents`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `results` | array of objects | yes | One per page read: `url`, `title`, `text`, and `highlights` or `summary` when asked for. |
| `meta` | object | yes | `resultCount` and `fetchedAt`. |

### Similar pages

Up to 25 pages similar to a URL: competitors, related articles, alternatives.

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/exa/find-similar` | `exa_find_similar_direct` | 0.01 |
| MPP | `POST /v1/mpp/exa/find-similar` | `exa_find_similar_mpp` | 0.01 |
| Account balance | MCP tool `web_find_similar` | `exa_find_similar` | 0.01 |

Body of `POST /v1/exa/find-similar`:

| Field | Type | Required | Default | Limits and notes |
| --- | --- | --- | --- | --- |
| `url` | string | yes | — | The page to find similar pages for. |
| `numResults` | integer | no | 10 | 1 to 25. |
| `excludeSourceDomain` | boolean | no | true | Leave out pages from the domain of `url`. |
| `includeDomains` | array of strings | no | — | Up to 50 domains to search in. |
| `excludeDomains` | array of strings | no | — | Up to 50 domains to leave out. |
| `contents` | object | no | — | The same `contents` object as Search. |

Response of `POST /v1/exa/find-similar`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `query` | string | yes | The `url` you sent. |
| `results` | array of objects | yes | The same result objects as Search. |
| `searchType` | string | no | The search type Exa used. |
| `meta` | object | yes | `resultCount` and `searchedAt`. |

### Cited answer

A direct answer to a question, grounded in a live web search, with the source pages as citations.

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/exa/answer` | `exa_answer_direct` | 0.01 |
| MPP | `POST /v1/mpp/exa/answer` | `exa_answer_mpp` | 0.01 |
| Account balance | MCP tool `web_answer` | `exa_answer` | 0.01 |

Body of `POST /v1/exa/answer`:

| Field | Type | Required | Default | Limits and notes |
| --- | --- | --- | --- | --- |
| `query` | string | yes | — | The question, 1 to 2,000 characters, not counting spaces at either end. |
| `text` | boolean | no | false | Include the full text of each citation. |

Response of `POST /v1/exa/answer`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `query` | string | yes | The question you sent. |
| `answer` | string | yes | The answer. |
| `citations` | array of objects | yes | The source pages, as result objects (`url`, `title`, and `text` when asked for). |
| `meta` | object | yes | `citationCount` and `answeredAt`. |

## Firecrawl

### Scrape a page

One URL rendered with JavaScript and converted to Markdown, and optionally its HTML, links or a summary. Use it when a plain fetch returns an empty page, a page that needs JavaScript, or a 403.

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/firecrawl/scrape` | `firecrawl_scrape_direct` | 0.015 |
| MPP | `POST /v1/mpp/firecrawl/scrape` | `firecrawl_scrape_mpp` | 0.015 |
| Account balance | MCP tool `web_scrape` | `firecrawl_scrape` | 0.015 |

Body of `POST /v1/firecrawl/scrape`:

| Field | Type | Required | Default | Limits and notes |
| --- | --- | --- | --- | --- |
| `url` | string | yes | — | The page to scrape. |
| `formats` | array of strings | no | ["markdown"] | 1 to 4 of `markdown`, `html`, `links` and `summary`. |
| `onlyMainContent` | boolean | no | true | Strip navigation, footers and other boilerplate. |
| `waitFor` | integer | no | — | Milliseconds to wait for dynamic content, 0 to 10,000. |
| `timeout` | integer | no | — | Milliseconds, 1,000 to 30,000. |

Response of `POST /v1/firecrawl/scrape`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `url` | string | yes | The final URL, after redirects. |
| `title` | string or null | yes | The page title. |
| `markdown` | string or null | yes | The page content as Markdown. |
| `html` | string or null | no | When `formats` asked for it. |
| `links` | array of strings | no | When `formats` asked for them. |
| `summary` | string or null | no | When `formats` asked for it. |
| `statusCode` | integer or null | yes | The HTTP status of the page. |
| `meta` | object | yes | `fetchedAt`, and `characters`, the length of `markdown`. |

### Search with page content

A web search with up to 20 results, and optionally the full Markdown of each result in the same call.

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/firecrawl/search` | `firecrawl_search_direct` | 0.03 |
| MPP | `POST /v1/mpp/firecrawl/search` | `firecrawl_search_mpp` | 0.03 |
| Account balance | MCP tool `web_search_scrape` | `firecrawl_search` | 0.03 |

Body of `POST /v1/firecrawl/search`:

| Field | Type | Required | Default | Limits and notes |
| --- | --- | --- | --- | --- |
| `query` | string | yes | — | 1 to 1,000 characters. |
| `limit` | integer | no | 5 | Results wanted, 1 to 20. |
| `lang` | string | no | — | Language code, 2 to 5 characters, such as `en` or `fr`. |
| `country` | string | no | — | Two-letter country code, such as `us` or `fr`. |
| `tbs` | string | no | — | Time filter, up to 40 characters: `qdr:d` (day), `qdr:w` (week), `qdr:m` (month). |
| `scrapeContent` | boolean | no | false | Also scrape each result to Markdown. |

Response of `POST /v1/firecrawl/search`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `query` | string | yes | The query you sent. |
| `results` | array of objects | yes | Each has `url`, `title` and `description`, and `markdown` when `scrapeContent` is `true`. |
| `meta` | object | yes | `resultCount` and `searchedAt`. |

## Serper (Google)

Google results through Serper: web, news, images and shopping. The four routes take the same body:

Body of `POST /v1/serper/search`, `POST /v1/serper/news`, `POST /v1/serper/images` and `POST /v1/serper/shopping`:

| Field | Type | Required | Default | Limits and notes |
| --- | --- | --- | --- | --- |
| `q` | string | yes | — | The Google query, 1 to 1,000 characters, not counting spaces at either end. |
| `gl` | string | no | us | Country code, exactly 2 letters, such as `us`, `fr` or `de`; sent to Serper in lower case. |
| `hl` | string | no | en | Interface language, 2 to 5 characters, such as `en` or `fr`. |
| `num` | integer | no | 10 | Results wanted, 1 to 100. The answer never has more than `num` results. |
| `page` | integer | no | 1 | Result page, 1 to 10. |
| `tbs` | string | no | — | Time filter, up to 40 characters: `qdr:d`, `qdr:w`, `qdr:m` or `qdr:y`. |

### Web results

Organic results with snippets, the answer box, the knowledge graph, people also ask and related searches.

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/serper/search` | `serper_search_direct` | 0.004 |
| MPP | `POST /v1/mpp/serper/search` | `serper_search_mpp` | 0.004 |
| Account balance | MCP tool `google_search` | `serper_search` | 0.004 |

Response of `POST /v1/serper/search`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `query` | string | yes | The query you sent. |
| `organic` | array of objects | yes | Each has `title` and `link`, and when Google gives them `snippet`, `position` and `date`. |
| `answerBox` | object or null | no | Google's answer box, `null` when there is none. |
| `knowledgeGraph` | object or null | no | Google's knowledge graph panel, `null` when there is none. |
| `peopleAlsoAsk` | array of objects | no | Related questions. |
| `relatedSearches` | array of objects | no | Each has a `query`. |
| `meta` | object | yes | `resultCount` and `searchedAt`. |

### News

Google News articles, with source and date.

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/serper/news` | `serper_news_direct` | 0.004 |
| MPP | `POST /v1/mpp/serper/news` | `serper_news_mpp` | 0.004 |
| Account balance | MCP tool `google_news` | `serper_news` | 0.004 |

Response of `POST /v1/serper/news`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `query` | string | yes | The query you sent. |
| `news` | array of objects | yes | Each has `title` and `link`, and when known `snippet`, `date`, `source`, `imageUrl` and `position`. |
| `meta` | object | yes | `resultCount` and `searchedAt`. |

### Images

Google Images results, with image URLs, dimensions and source pages.

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/serper/images` | `serper_images_direct` | 0.004 |
| MPP | `POST /v1/mpp/serper/images` | `serper_images_mpp` | 0.004 |
| Account balance | MCP tool `google_images` | `serper_images` | 0.004 |

Response of `POST /v1/serper/images`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `query` | string | yes | The query you sent. |
| `images` | array of objects | yes | Each has `imageUrl`, and when known `title`, `imageWidth`, `imageHeight`, `thumbnailUrl`, `source`, `link` and `position`. |
| `meta` | object | yes | `resultCount` and `searchedAt`. |

### Shopping

Google Shopping products, with price, seller and rating.

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/serper/shopping` | `serper_shopping_direct` | 0.004 |
| MPP | `POST /v1/mpp/serper/shopping` | `serper_shopping_mpp` | 0.004 |
| Account balance | MCP tool `google_shopping` | `serper_shopping` | 0.004 |

Response of `POST /v1/serper/shopping`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `query` | string | yes | The query you sent. |
| `shopping` | array of objects | yes | Each has `title`, and when known `source`, `link`, `price`, `rating`, `ratingCount`, `imageUrl` and `position`. |
| `meta` | object | yes | `resultCount` and `searchedAt`. |

## Example

An Exa search for five results. Called without payment, it answers `402` with the price in the `PAYMENT-REQUIRED` header; [Copy-paste examples](/docs/payments/examples) shows how to sign the payment and send the request again, in curl, TypeScript and Python.

```bash
curl -sS -i https://api.munition.io/v1/exa/search \
  -H 'Content-Type: application/json' \
  --data '{"query":"x402 payment protocol for AI agents","numResults":5,"type":"auto"}'
```

Paid, it costs 0.01 USDC and answers `200`. A response of `POST /v1/exa/search` looks like this:

```json
{
  "query": "x402 payment protocol for AI agents",
  "results": [
    {
      "title": "x402 — HTTP-native payments",
      "url": "https://www.x402.org/",
      "publishedDate": "2025-05-06T00:00:00.000Z",
      "author": null,
      "score": 0.21
    }
  ],
  "searchType": "neural",
  "meta": { "resultCount": 1, "searchedAt": "2026-09-09T00:00:00.000Z" }
}
```
