Research a question on the live web and answer it with sources cited

POST /v1/ask/web

Researches a question on the live web and answers it with its sources cited.

This is the DEEP one. It plans the question into topics, runs several web searches, FETCHES AND READS the pages it finds, ranks them, and writes a grounded answer with inline markdown citations. Use it for anything that needs evidence, comparison or current fact — "what changed in X", "compare A and B", "is this claim true". For a plain list of links, use search_web instead; for one page you already have the URL of, use read_page.

mode buys depth: search is a single fast pass, news biases to recency, research plans and iterates, deep surveys widest. sources narrows the evidence to web, news, academic, github, reddit or x — each becomes a site-scoped search, which is how this reaches X/Twitter posts.

EVERY CITATION IS A PAGE THIS CALL FETCHED. That is a property of the text and not an instruction to the model: each source is fenced with a per-request nonce so a crawled page cannot print itself a source number, and every markdown link in the answer is checked against the gathered set before it is returned. So a link in answer always appears in sources, and a page that was not read cannot be cited.

It is BOUNDED and it degrades rather than failing: a mode's rounds, wall clock and token ceiling all cap it, and a search that finds little or a page that will not load yields a thinner answer, never an error. A validated principal is required, and the answer is billed once to that principal's org.

Request

5 fields, body application/json (required).

Response

200 body — 10 fields.

Failure carries the platform error shape — see Errors.

Examples

hanzo ask web

import { Configuration, AskApi } from 'hanzoai';

const api = new AskApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.researchWeb({ language: "<language>", max_sources: 0 });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AskApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AskApi(client).research_web(language="<language>", max_sources=0)

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

resp, _, err := client.AskAPI.ResearchWeb(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, ask_api};

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

let result = ask_api::research_web(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AskApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new AskApi(client).researchWeb();

curl -X POST https://api.hanzo.ai/v1/ask/web \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "language": "<language>",
       "max_sources": 0
     }'

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "ask",
         "arguments": {
           "op": "research_web",
           "input": {
             "language": "<language>",
             "max_sources": 0
           }
         }
       }
     }'

Ask API · All Hanzo APIs · Interactive reference