# Web Search, News & Page Reader

**Web Search, News & Page Reader** is an independently documented x402 Atlas bridge at https://websearch.use.x402atlas.com.
This document describes only this bridge; it does not aggregate routes, schemas,
or content from any other bridge.

## How payment works

Paid operations use the [x402 payment protocol](https://x402.org) and settle in
USDC. Atlas supports deployments on Base, Polygon, and Arbitrum, plus configured
Solana networks. This bridge currently advertises Arbitrum One (`eip155:42161`), Base (`eip155:8453`), Polygon (`eip155:137`), Solana mainnet (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`).

1. Send the HTTP request without a payment signature.
2. Read the `402 Payment Required` response. Its `accepts` entries are the
   authoritative network, asset, amount, and recipient options for that call.
3. Select an option, sign it with an x402-compatible wallet or SDK, and repeat
   the request with the `PAYMENT-SIGNATURE` header. The successful response is
   returned after verification and settlement.

TypeScript clients can automate the challenge, signing, and retry flow with
[`x402-fetch`](https://www.npmjs.com/package/x402-fetch) or
[`x402-axios`](https://www.npmjs.com/package/x402-axios). Fund a dedicated
wallet only with the working USDC balance it needs and keep that key separate
from treasury accounts.

## Pricing

Atlas route prices start at $0.005 per successful call. This bridge's fallback
price is $0.005; operations below state their exact configured price in
`x-x402` and `x-payment-info`. The live `402` challenge remains authoritative.

## Worked payment example

Request one documented operation without a signature to inspect its live terms:

```bash
curl -i 'https://websearch.use.x402atlas.com/extract?chunks_per_source=3&format=markdown&query=artificial+intelligence&urls=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FArtificial_intelligence'
# HTTP/1.1 402 Payment Required
# Read accepts[].network, asset, amount, and payTo from this response.
```

Sign one accepted option and repeat the identical request with the
`PAYMENT-SIGNATURE` header. Do not invent or cache payment terms; read them from
the current challenge.

## Use this API

- Interactive reference: https://websearch.use.x402atlas.com/docs
- OpenAPI 3.1 specification: https://websearch.use.x402atlas.com/openapi.json
- Agent-readable route corpus: https://websearch.use.x402atlas.com/llms.txt
- Endpoint index: https://websearch.use.x402atlas.com/index.json

Use the operation schemas and examples below to construct requests. Copy the
server URL, path, method, parameters, and request body from the operation you
want to call. Path and query examples are concrete and can be used directly.

## Atlas response metadata

Successful JSON responses include an additive top-level `_atlas` block, kept
separate from the bridge's data fields. `_atlas.docs` links this bridge's
`/llms.txt` corpus. `_atlas.related` suggests adjacent APIs, each with a callable
`url`, its own `docs` link, and a short `summary`. Suppress this block by sending
`X-Atlas-Meta: none` or by adding `?_atlas=0` to the request.

## Errors and compatibility

Validation failures use HTTP `400`. Paid operations may return `402` before
dispatch. Upstream and internal failures use the documented `5xx` responses.
Clients should rely on documented fields and tolerate additive response fields,
including `_atlas` unless they explicitly opt out.

## Protocol reference

- x402 protocol and SDKs: https://x402.org

## Web Search, News & Page Reader

Docs: https://websearch.use.x402atlas.com/docs · OpenAPI: https://websearch.use.x402atlas.com/openapi.json

### GET /extract

Read any web page or article: fetch up to 5 URLs in one batch call and extract the main content as clean, LLM-ready markdown or plain text. Convert webpages to markdown, scrape page text, pull article content for RAG ingestion and AI agent context.

Fetch web pages and extract their main content as clean, LLM-ready markdown (or plain text) — boilerplate stripped. Pass up to 5 URLs (repeat `urls=`) in one batch call. Use this for RAG ingestion, feeding article content into an agent's context, or turning a known URL into readable text. `/search` finds URLs; `/extract` reads them.

**Price:** $0.01 per call.

Parameters:
- `chunks_per_source` (optional, integer) — Relevant snippets per URL, 1..5 (requires query); minimum: `1`, maximum: `5`; example: `3`
- `format` (optional, string) — Output content format; allowed: ["markdown","text"], default: `"markdown"`; example: `"markdown"`
- `query` (optional, string) — Optional intent — extracted chunks are reranked by relevance to it; maxLength: `1000`; example: `"artificial intelligence"`
- `urls` (required, string or array) — One URL or an array of up to 5 absolute http(s) URLs to extract content from; example: `"https://en.wikipedia.org/wiki/Artificial_intelligence"`

Example:

```sh
curl 'https://websearch.use.x402atlas.com/extract?chunks_per_source=3&format=markdown&query=artificial+intelligence&urls=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FArtificial_intelligence'
```

Response example:

```json
{
  "queried_at": "2026-07-01T12:00:00Z",
  "results": [
    {
      "content": "# Artificial intelligence\n\nArtificial intelligence (AI) is intelligence exhibited by machines...",
      "url": "https://en.wikipedia.org/wiki/Artificial_intelligence"
    }
  ]
}
```

### GET /google-search

Perform a Google search and return structured results. Returns title, URL, snippet, position for each result. Google search SERP results for AI agents: organic results as clean JSON, scoped by country (ISO 3166) and language (ISO 639-1), up to 20 results per call.

Perform a Google search and return structured organic results — `position`, `title`, `url` and `snippet` per result, in ranking order. Pass the search `query`; optionally scope with `country` (ISO 3166-1 alpha-2/alpha-3/numeric code or exact country name; `UK` = `GB`; omit for unscoped global results), `language` (ISO 639-1, optionally with a region such as `pt-BR`) and `num_results` (1–20, default 10). Unrecognised `country` or malformed `language` is rejected with 400 before any payment is taken. No matches return 200 with an empty `results` array. An omitted `query` returns the declared sample with a note and does not run a search. For ranked results with relevance scores and an LLM answer use `/search`; to read a page use `/extract`.

**Price:** $0.108 per call.

Parameters:
- `country` (optional, string) — Country to scope results to, as an ISO 3166-1 alpha-2 code (MX), alpha-3 code (MEX), numeric code (484), or exact country name (Mexico). "UK" is accepted as an alias for GB. Unrecognised values are rejected before the search runs rather than silently ignored. Omit for unscoped global results.; maxLength: `64`; example: `"US"`
- `language` (optional, string) — Language for results, as an ISO 639-1 code ("en"), optionally with a region ("pt-BR"). Validated for shape and rejected before the search runs if malformed, rather than silently ignored. Omit for Google's default.; pattern: `"^[A-Za-z]{2}(-[A-Za-z]{2})?$"`; example: `"en"`
- `num_results` (optional, integer) — Number of results (default 10, max 20); default: `10`, minimum: `1`, maximum: `20`; example: `10`
- `query` (required, string) — Search query; maxLength: `400`; example: `"best electric cars 2026"`

Example:

```sh
curl 'https://websearch.use.x402atlas.com/google-search?country=US&language=en&num_results=10&query=best+electric+cars+2026'
```

Response example:

```json
{
  "country": "US",
  "language": "en",
  "queried_at": "2026-07-01T12:00:00Z",
  "query": "best electric cars 2026",
  "results": [
    {
      "position": 1,
      "snippet": "Our ranking of the best EVs you can buy in 2026, from affordable hatchbacks to luxury SUVs.",
      "title": "The Best Electric Cars of 2026 - Car and Driver",
      "url": "https://www.caranddriver.com/rankings/best-electric-cars"
    },
    {
      "position": 2,
      "snippet": "Edmunds experts test and rank the top electric vehicles on sale this year.",
      "title": "Best Electric Cars 2026 | Edmunds",
      "url": "https://www.edmunds.com/electric-car/best-electric-cars/"
    }
  ]
}
```

### GET /search

Real-time web search for AI agents — search the web and get ranked SERP-style results as clean JSON: title, URL, snippet, relevance score, optional LLM-generated answer. Find up-to-date information online — latest news, current events, finance. Date, domain and exact-phrase filters.

Real-time web search that returns ranked, SERP-style results as clean JSON — title, URL, snippet, relevance score, and an optional LLM-generated answer. Pass your `query` and optional filters (date range, domain include/exclude, exact phrase) as query parameters. Use this to ground an agent in current information (news, events, finance). For higher precision with multiple query-focused snippets per source use `/search/advanced`; to pull the full text of a specific page use `/extract`.

**Price:** $0.01 per call.

Parameters:
- `chunks_per_source` (optional, integer) — Content snippets per source, 1..3 (fast depth only); minimum: `1`, maximum: `3`; example: `2`
- `country` (optional, string) — Boost results from a country, letters and spaces only (topic general only), e.g. united states
- `end_date` (optional, string) — Only results published before this date (YYYY-MM-DD)
- `exact_match` (optional, boolean) — Only return results containing the exact quoted phrases in the query; default: `false`
- `exclude_domains` (optional, array) — Exclude results from these domains; maxItems: `150`
- `include_answer` (optional, boolean or string) — Include an LLM-generated answer: true/basic for quick, advanced for detailed
- `include_domains` (optional, array) — Only include results from these domains; maxItems: `300`
- `include_raw_content` (optional, boolean or string) — Include cleaned page content per result: true/markdown or text
- `max_results` (optional, integer) — Maximum results to return, 1..20; default: `5`, minimum: `1`, maximum: `20`
- `query` (required, string) — The search query to execute; maxLength: `1000`; example: `"latest developments in AI agents"`
- `search_depth` (optional, string) — Relevance vs latency tradeoff; allowed: ["basic","fast","ultra-fast"], default: `"basic"`; example: `"fast"`
- `start_date` (optional, string) — Only results published after this date (YYYY-MM-DD)
- `time_range` (optional, string) — Filter results by recency; allowed: ["day","week","month","year","d","w","m","y"]
- `topic` (optional, string) — Search category; allowed: ["general","news","finance"], default: `"general"`

Example:

```sh
curl 'https://websearch.use.x402atlas.com/search?chunks_per_source=2&query=latest+developments+in+AI+agents&search_depth=fast'
```

Response example:

```json
{
  "queried_at": "2026-07-01T12:00:00Z",
  "query": "latest developments in AI agents",
  "results": [
    {
      "content": "A short, relevant snippet from the page...",
      "score": 0.87,
      "title": "AI agents in 2026: what changed",
      "url": "https://example.com/ai-agents-2026"
    }
  ]
}
```

### GET /search/advanced

Deep web research for AI agents — advanced search returning the highest-relevance results with multiple query-focused snippets per source, plus an optional LLM-generated answer grounded in the returned sources when include_answer is set. One-call research assistant for high-precision queries; news and finance topics, date and domain filters.

Deep web research in one call: advanced search returns the highest-relevance sources with multiple query-focused snippets each, plus an optional LLM-generated answer grounded in those sources when you set `include_answer`. Same query parameters and filters as `/search` (date, domain, exact phrase), tuned for precision over breadth — use it as a one-call research assistant for high-stakes queries. Costs more than `/search`; reach for it when snippet depth and a grounded answer matter.

**Price:** $0.025 per call.

Parameters:
- `chunks_per_source` (optional, integer) — Content snippets per source, 1..3; minimum: `1`, maximum: `3`; example: `2`
- `country` (optional, string) — Boost results from a country, letters and spaces only (topic general only), e.g. united states
- `end_date` (optional, string) — Only results published before this date (YYYY-MM-DD)
- `exact_match` (optional, boolean) — Only return results containing the exact quoted phrases in the query; default: `false`
- `exclude_domains` (optional, array) — Exclude results from these domains; maxItems: `150`
- `include_answer` (optional, boolean or string) — Include an LLM-generated answer: true/basic for quick, advanced for detailed
- `include_domains` (optional, array) — Only include results from these domains; maxItems: `300`
- `include_raw_content` (optional, boolean or string) — Include cleaned page content per result: true/markdown or text
- `max_results` (optional, integer) — Maximum results to return, 1..20; default: `5`, minimum: `1`, maximum: `20`
- `query` (required, string) — The search query to execute; maxLength: `1000`; example: `"latest developments in AI agents"`
- `start_date` (optional, string) — Only results published after this date (YYYY-MM-DD)
- `time_range` (optional, string) — Filter results by recency; allowed: ["day","week","month","year","d","w","m","y"]
- `topic` (optional, string) — Search category; allowed: ["general","news","finance"], default: `"general"`

Example:

```sh
curl 'https://websearch.use.x402atlas.com/search/advanced?chunks_per_source=2&query=latest+developments+in+AI+agents'
```

Response example:

```json
{
  "queried_at": "2026-07-01T12:00:00Z",
  "query": "latest developments in AI agents",
  "results": [
    {
      "content": "A short, relevant snippet from the page...",
      "score": 0.87,
      "title": "AI agents in 2026: what changed",
      "url": "https://example.com/ai-agents-2026"
    }
  ]
}
```

### GET /search/bulk

Bulk web search — run up to 5 search queries in one paid call and get ranked results per query (title, URL, snippet, relevance score) as clean JSON. Same news, finance, date-range, country and domain filters as single web search, applied to every query. One payment instead of five for research fan-out, multi-query RAG retrieval and agent planning.

Run up to 5 web searches in one paid call: repeat `query` (`?query=a&query=b`) and get ranked, SERP-style results per query — title, URL, snippet, relevance score — in submission order under `searches`. Every filter (`topic`, `time_range`, `start_date`/`end_date`, `country`, `include_domains`/`exclude_domains`, `exact_match`, `max_results`, `search_depth` basic/fast/ultra-fast) applies to all queries. Searches run concurrently, so a batch takes about as long as its slowest query. A query whose upstream search fails is listed in `failed_queries` and the rest are still answered; only a batch with no successful search answers non-2xx. LLM answers and raw page content are not available on this route — use `/search` for one query with `include_answer`, `/extract` to read pages.

**Price:** $0.045 per call.

Parameters:
- `country` (optional, string) — Boost results from a country, letters and spaces only (topic general only), e.g. united states
- `end_date` (optional, string) — Only results published before this date (YYYY-MM-DD)
- `exact_match` (optional, boolean) — Only return results containing the exact quoted phrases in the query; default: `false`
- `exclude_domains` (optional, array) — Exclude results from these domains; maxItems: `150`
- `include_domains` (optional, array) — Only include results from these domains; maxItems: `300`
- `max_results` (optional, integer) — Maximum results per query, 1..20; default: `5`, minimum: `1`, maximum: `20`
- `query` (required, string or array) — Repeat the parameter per query, 1..5 (?query=a&query=b); each up to 1000 chars; example: `"best python web scraping library"`
- `search_depth` (optional, string) — Relevance vs latency tradeoff; allowed: ["basic","fast","ultra-fast"], default: `"basic"`
- `start_date` (optional, string) — Only results published after this date (YYYY-MM-DD)
- `time_range` (optional, string) — Filter results by recency; allowed: ["day","week","month","year","d","w","m","y"]
- `topic` (optional, string) — Search category; allowed: ["general","news","finance"], default: `"general"`

Example:

```sh
curl 'https://websearch.use.x402atlas.com/search/bulk?query=best+python+web+scraping+library'
```

Response example:

```json
{
  "queried_at": "2026-07-01T12:00:00Z",
  "searches": [
    {
      "query": "best python web scraping library",
      "results": [
        {
          "content": "A short, relevant snippet from the page...",
          "score": 0.91,
          "title": "Best Python web scraping libraries in 2026",
          "url": "https://example.com/python-scraping-libraries"
        }
      ]
    }
  ]
}
```