# Create scrape

URL: https://docs.hanzo.ai/docs/openapi/websearch/post-websearch-scrape

> Takes {url} and answers {success, data:{markdown, metadata}} — the exact contract a firecrawl client decodes.

`POST /v1/websearch/scrape`

> [Websearch →](https://docs.hanzo.ai/docs/openapi/websearch) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                            |
| ------------- | ------------------------------------------ |
| **Address**   | `https://api.hanzo.ai/v1/websearch/scrape` |
| **Method**    | `POST`                                     |
| **Operation** | `post_websearch_scrape`                    |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY`     |

Takes {url} and answers {success, data:{markdown, metadata}} — the exact contract a firecrawl client decodes. The fetch, extraction and optional browser render run in-process; there is no crawler pod to be down.

The shared service key is required as an Authorization Bearer, compared in constant time: unset on the deployment is 503, missing or wrong is 401. Unlike search, a validated principal does NOT substitute for it — this is the service-to-service endpoint.

A page is archived under the caller's own org and project, taken from the verified principal when there is one, so a scrape lands in the same corpus /v1/crawl fills and a URL already read under that scope is answered from the archive without touching the network. A service caller carrying no principal shares the unscoped prefix.

The URL is caller-supplied and fetched from INSIDE the cluster, which makes this a request-forgery primitive by construction: in-namespace service DNS and a cloud metadata endpoint that hands credentials to anyone who asks are both a resolution away. Only http and https are accepted, and every address actually dialled must be public unicast — loopback, link-local, private and multicast are refused. The check lives in the DIALER rather than on the hostname, because resolving a name to validate it and then letting the transport resolve it again is a gap DNS rebinding walks straight through; redirects re-enter the same dialer, so a public URL that bounces to the metadata address is refused at the hop that matters.

The one thing to get right: FAILURE IS 200. A missing or unparseable url, a body over the 1 MiB read cap, and a fetch that could not be completed all answer HTTP 200 with success:false and a reason — a firecrawl client reads data.success, not the status line. Only the two auth refusals use a status code, so a caller that branches on HTTP status alone will read every failed scrape as a success.

## Request

The document declares no body for `POST /v1/websearch/scrape`. The handler is typed in cloud but its shape is not yet emitted, so the fields are not listed here — ask MCP's `describe` for `post_websearch_scrape`, which answers from the running route.

## Response

The document declares no response body for this operation. It answers `200` on success and the platform error shape on failure — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo websearch scrape
```

**SDK**

**.ts**

```ts
import { Configuration, WebsearchApi } from 'hanzoai';

const api = new WebsearchApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postWebsearchScrape();
```

**.py**

```python
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import WebsearchApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = WebsearchApi(client).post_websearch_scrape()
```

**.go**

```go
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.WebsearchAPI.PostWebsearchScrape(context.Background()).Execute()
if err != nil {
	return err
}
```

**.rs**

```rust
use hanzo_client::apis::{configuration::Configuration, websearch_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = websearch_api::post_websearch_scrape(&cfg, Default::default()).await?;
```

**.java**

```java
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.WebsearchApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new WebsearchApi(client).postWebsearchScrape();
```

**HTTP**

```bash
curl -X POST https://api.hanzo.ai/v1/websearch/scrape \
  -H "Authorization: Bearer $HANZO_API_KEY"
```

**MCP**

MCP declares no tool for **websearch** — `tools/list` on `https://api.hanzo.ai/v1/mcp` names the products it does reach. Use HTTP or an SDK.

---

[Websearch API](https://docs.hanzo.ai/docs/openapi/websearch) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)