From f9e2316e6dbfa643eb05961ee832171e6299d3f4 Mon Sep 17 00:00:00 2001 From: 1bcMax Date: Wed, 12 Aug 2026 16:56:34 -0500 Subject: [PATCH] docs(surf): query-string placement made explicit + web/fetch example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An external integrator built calls from the CDP Bazaar record, which (until blockrun#373) declared GET params under body — their GET /v1/surf/web/fetch calls all failed. The discovery record is fixed; this makes the docs page state the placement rule explicitly and adds an example for the exact endpoint that was reported. --- docs/api-reference/surf.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/api-reference/surf.md b/docs/api-reference/surf.md index 957cda0..25405a3 100644 --- a/docs/api-reference/surf.md +++ b/docs/api-reference/surf.md @@ -54,7 +54,7 @@ All Surf endpoints route through: https://blockrun.ai/api/v1/surf/ ``` -Method follows the upstream — most are `GET` with query string params; the two SQL/structured-query endpoints (`onchain/sql`, `onchain/query`) are `POST` with JSON bodies, while `onchain/schema` is a `GET`. +Method follows the upstream — most are `GET` with **query string** params (never a request body); the two SQL/structured-query endpoints (`onchain/sql`, `onchain/query`) are `POST` with JSON bodies, while `onchain/schema` is a `GET`. The x402 discovery record (`extensions.bazaar` on the 402 response) declares GET params as `queryParams` — agents building calls from the CDP Bazaar catalog get the correct placement. Per-endpoint parameter docs live at [agents.asksurf.ai/docs](https://agents.asksurf.ai/docs). --- @@ -72,6 +72,17 @@ curl "https://blockrun.ai/api/v1/surf/market/price?symbol=BTC" \ # → token price history JSON ``` +### Fetch a web page as clean markdown (Tier 2) + +The `url` parameter goes in the query string — this is a `GET`, so there is no +request body: + +```bash +curl -H "X-Payment: " \ + "https://blockrun.ai/api/v1/surf/web/fetch?url=https%3A%2F%2Fexample.com" +# → { "data": { "markdown": "..." } } +``` + ### Fear & Greed snapshot (Tier 1) ```bash