AI web search

The answer-engine service searches the web, reads the pages that matter, and writes an answer with numbered citations. Your app sends a question and gets back the answer text plus the list of sources it was built from.

The request and response shapes match the open-source Vane search API, so a client written for Vane works here with only the address and the authorization header changed.

Ask a question

const result = await hive.services.invokeOperation("answer-engine", "searches.create", {
  query: "How well do heat pumps work below freezing?",
  optimizationMode: "balanced",
  sources: ["web"],
});

console.log(result.result.message);   // the answer, with [1] style citations
console.log(result.result.sources);   // what each citation number points to

Every source carries the page title and address, so your app can render citations as links:

{
  "message": "Modern cold-climate units keep working near -25 °C [1], though their efficiency falls as it gets colder [2].",
  "sources": [
    { "content": "…", "metadata": { "title": "Cold climate heat pumps", "url": "https://example.com/a", "source": "web", "read": true } },
    { "content": "…", "metadata": { "title": "Efficiency in winter", "url": "https://example.org/b", "source": "web", "read": false } }
  ]
}

A source with read: true was opened and read in full; the rest are search results with their summary text.

How hard it should look

optimizationMode sets how much work goes into one answer.

Only certain sites

Pass includeDomains to search nothing else, and excludeDomains to keep sites out. Both take plain site addresses; a pasted address with https:// and a trailing slash is accepted and tidied.

const result = await hive.services.invokeOperation("answer-engine", "searches.create", {
  query: "transformer scaling laws",
  includeDomains: ["arxiv.org", "nature.com"],
});

The restriction is applied twice — in the query, and again on the results — because search engines treat a site restriction as a hint rather than a rule.

Where to look

sources chooses which parts of the web are searched. Ask for more than one when the question needs both.

A lane is only used when the question actually calls for it, so asking for all three costs nothing extra on a question that needs none of them.

Images and videos

Set includeMedia: true and pictures or clips come back alongside the answer, but only when the question is one they actually help with — “what does a heat pump look like” gets images, “what does a heat pump cost” does not.

Images carry their licence and the page they came from, so they can be credited. You can also search either on its own:

const images = await hive.services.invokeOperation("answer-engine", "images.search", { query: "cold climate heat pump" });
const videos = await hive.services.invokeOperation("answer-engine", "videos.search", { query: "how to install a heat pump" });

Answer from your own documents

Send the text with the request and add documents to sources. Nothing is stored — the text is used for this one search and then gone.

const result = await hive.services.invokeOperation("answer-engine", "searches.create", {
  query: "What COP did unit 3 measure at -19 °C?",
  sources: ["documents"],
  documents: [{ title: "Site log", text: "At -19C the measured COP was 1.9…" }],
});

Ask for ["documents", "web"] and both feed one answer, with citations telling them apart.

Instant answers

When a question is arithmetic, a currency conversion, the weather somewhere, or a crypto price, the result carries a widgets array with the answer already worked out. These cost no extra model time — the parameters come from the same turn that sorts the question — and the written answer is told not to contradict them.

Share prices are deliberately absent: there is no keyless quote source we trust, and a stale price is worse than none.

Follow-up questions

Set includeSuggestions: true and the result carries a few follow-ups drawn from what the answer left open — not from the question, so they point at the gaps rather than rephrasing what was asked.

Streaming

Set stream: true to receive the answer as it is written. The response is newline-delimited JSON: one complete object per line.

Render step frames if you want to show the work in progress, or ignore them and wait for response.

If the connection drops

A quality search can run for minutes. The stream’s first frame is session, carrying the search’s id, and the same id comes back in the x-hivemindos-answer-session header. If the connection drops, reconnect with it:

await hive.services.invokeOperation("answer-engine", "searches.reconnect", {}, {
  pathParameters: { searchId },
});

Everything the search has produced replays, then live frames continue. The run does not stop when you disconnect, so the model time you already paid for is not lost. The window stays open for fifteen minutes after the answer finishes.

Answer models

const models = await hive.services.invokeOperation("answer-engine", "models.list");

Pass a chatModel on the request to pick one; leave it out to use the recommended default. Answers are written by managed HivemindOS models and billed to the same Agent Credit balance as the rest of the API — this service adds no separate charge on top of the model it uses.

Permissions

A key needs services:read and services:invoke, and its allowed services must include answer-engine. Restrict it to answer-engine.searches.create if that is the only thing the key should be able to do.

What it will not do

• It will not answer from memory when the sources do not cover the question. It says what is missing instead.
• It will not cite a page it did not retrieve.
• It will not show the same story five times because five outlets carried it: near-identical results are folded into one citation.
• It treats page text as untrusted. Instructions found on a web page are reported as content, never followed.

Return to the SuperAgent API quickstart, or open service access and endpoint limits.