---
name: hushsearch
description: Search, scrape, crawl, browse and research the web through the HushSearch API. Use when a task needs live web results, the content of a URL, a whole site, a rendered page or PDF, or a cited answer.
---

# HushSearch web data

HushSearch is one API for web data: 35 endpoints behind one key, priced per call in credits.

## Setup

- Base URL: `https://api.hushsearch.io`
- Send `X-API-Key: $HUSHSEARCH_API_KEY` on every request. Keys: http://localhost:3000/dashboard/keys (new accounts get 500 free credits).
- Call paths exactly as listed, including the trailing slash; the bare path redirects and POST clients do not follow it.
- Every response includes `credits_used`, `credits_remaining` and `response_time_ms`.

## Choosing an endpoint

- Need current facts or links: `POST /v1/search/` with `{"query": "…"}`.
- Need an answer with citations: `POST /v1/answer/` with `{"query": "…"}`.
- Need a page's content: `POST /v1/scrape/` with `{"url": "…"}` (Markdown by default).
- Need a whole site: `POST /v1/map/` to list URLs, then `POST /v1/crawl/` or `POST /v1/batch-scrape/`.
- Page renders with JavaScript or is a PDF: `POST /v1/render-extract/` or `POST /v1/docling-markdown/`.
- Work that may take over 30 seconds: `POST /v1/jobs/` and poll `GET /v1/jobs/{id}`.

## Errors

- 401: missing or invalid key. 402: out of credits; stop and tell the user.
- 422: invalid body; read `detail`. 429: wait for `Retry-After` seconds, then retry once.

## Example

```bash
curl -X POST https://api.hushsearch.io/v1/search/ \
  -H "X-API-Key: $HUSHSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "best open-source vector databases", "num_results": 5}'
```

## All endpoints

### Search

- `POST /v1/search/` — Live web results as clean JSON — titles, URLs, snippets, instant answers. (1 credit)
- `POST /v1/search/stream` — The same search, streamed as server-sent events while engines answer. (1 credit)
- `POST /v1/search/batch` — Up to many queries in one request; one credit per non-empty query. (1 credit / query)
- `POST /v1/search/similar` — Pages semantically similar to a URL or a passage of text. (1 credit)

### Answers & research

- `POST /v1/answer/` — A grounded answer with numbered citations and a groundedness score. (4 credits)
- `POST /v1/research/` — Plans sub-queries, reads sources and writes a cited report. (8 credits)
- `POST /v1/search-and-summarize/` — Search plus a short synthesized summary with sources. (5 credits)
- `POST /v1/context/` — A token-budgeted context pack for coding and RAG agents. (2 credits)
- `POST /v1/agent/` — Give a goal; get a cited result plus the searches used to reach it. (4 credits)

### Scrape & extract

- `POST /v1/scrape/` — One page as Markdown, HTML or text, with optional query highlights. (2 credits)
- `POST /v1/extract/` — Main content of a URL as clean Markdown plus metadata and links. (3 credits)
- `GET /v1/reader/` — Prefix-style URL → LLM-ready Markdown in a single GET. (2 credits)
- `POST /v1/contents/` — Text, highlights and summaries for a list of URLs. (2 credits / URL)
- `POST /v1/structured-extract/` — Typed JSON from a page using a schema or a plain-English prompt. (4 credits)
- `POST /v1/search-extract/` — Search, rerank and extract structured fields from the top hits. (6 credits)
- `POST /v1/multi-extract/` — One schema applied across many URLs, optionally grounded by search. (4 credits)

### Crawl & map

- `POST /v1/map/` — Every link discovered on a site, with sitemap enrichment. (1 credit)
- `POST /v1/crawl/` — Follow a site's links to a depth and return every page as Markdown. (3 credits)
- `POST /v1/crawl/pipeline` — Map → filter → scrape in one call with include/exclude rules. (4 credits)
- `POST /v1/batch-scrape/` — Scrape many URLs in parallel; two credits per URL. (2 credits / URL)

### Browsers

- `POST /v1/screenshot/` — A rendered PNG of any page, viewport or full length. (3 credits)
- `POST /v1/browser/sessions` — Durable headless sessions: navigate, read content, cookies, evaluate. (3 credits)
- `POST /v1/browser-execute/` — Run a list of actions — click, type, scroll, wait, extract — in a session. (2 credits)
- `POST /v1/agent-scrape/` — A goal-driven browser that navigates until it can return clean content. (5 credits)

### Documents

- `POST /v1/render-extract/` — Renders JavaScript, captures a PDF and runs Docling for layout-aware Markdown. (6 credits)
- `POST /v1/docling-markdown/` — PDF, Office files or rendered pages into structured Markdown. (4 credits)
- `POST /v1/docling-ocr/` — OCR for scanned documents and images, returned as Markdown. (3 credits)
- `POST /v1/docling-structured/` — The full Docling layout tree — headings, tables, reading order — as JSON. (6 credits)

### Platform

- `POST /v1/embeddings/` — Dense vectors for one or many inputs; one credit per input. (1 credit / input)
- `POST /v1/rerank/` — Score documents against a query with a cross-encoder. (1 credit)
- `POST /v1/jobs/` — Queue research, crawl, batch or multi-extract work; poll or get a webhook. (5 credits / job (research 8 · crawl 5 · batch 3 · multi-extract 4))
- `POST /v1/change-monitor/` — Snapshot a page and report added, removed and changed content since last check. (2 credits)
- `GET /v1/knowledge` — Look up an entity in the knowledge index by name. (1 credit)
- `POST /v1/enrich` — Build a structured entity record from a name, URL or text. (4 credits)
- `POST /v1/mcp/` — Every capability as Model Context Protocol tools over JSON-RPC. (billed per tool call)

Full reference for language models: http://localhost:3000/llms-full.txt
MCP server (for hosts that support it): https://api.hushsearch.io/v1/mcp/
