API Reference

Search API

The Search API performs federated multi-backend web search with HyperFusion neural ranking, QATBE token-budgeted extraction, and SCS semantic segmentation — all in a single request.

POST/v1/search

Request

Headers

Header	Value	Required
`Authorization`	`Bearer hsx_...`	Yes
`Content-Type`	`application/json`	Yes

Body parameters

Parameter	Type	Required	Description
`query`	string	Yes	Search query. Max 500 characters.
`tier`	string	No	Detail level: `key_facts` (~200 tok), `summary` (~1k tok, default), `detailed` (~5k tok), `complete` (~20k tok).
`token_budget`	integer	No	Override tier with exact token budget. Range: 100–10,000.
`max_sources`	integer	No	Maximum sources to search. Range: 1–20. Default: 10.
`backends`	string[]	No	Force specific backends: `brave`, `google`, `bing`, `stackoverflow`, `github`, `reddit`. Default: auto-selected by ABS algorithm.
`language`	string	No	BCP-47 language code for results (e.g. `en`, `de`). Default: `en`.
`freshness`	string	No	Filter by date: `day`, `week`, `month`, `year`. Default: no filter.
`include_domains`	string[]	No	Restrict results to these domains.
`exclude_domains`	string[]	No	Exclude results from these domains.

Example request

search.sh

curl -X POST https://api.hypersearchx.zuhabul.com/v1/search \
  -H "Authorization: Bearer hsx_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "rust async programming best practices",
    "tier": "detailed",
    "max_sources": 8,
    "freshness": "year"
  }'

search.ts

const res = await fetch("https://api.hypersearchx.zuhabul.com/v1/search", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.HSX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "rust async programming best practices",
    tier: "detailed",
    max_sources: 8,
    freshness: "year",
  }),
});
const data = await res.json();

search.py

import os, requests

r = requests.post(
    "https://api.hypersearchx.zuhabul.com/v1/search",
    headers={"Authorization": f"Bearer {os.environ['HSX_API_KEY']}"},
    json={
        "query": "rust async programming best practices",
        "tier": "detailed",
        "max_sources": 8,
        "freshness": "year",
    }
)
r.raise_for_status()
data = r.json()

Response

response.json

{
  "meta": {
    "query": "rust async programming best practices",
    "tier": "detailed",
    "tokens_used": 4821,
    "sources_count": 8,
    "duration_ms": 1247,
    "result_id": "09742460-58db-44fd-9036-502ed26565e2",
    "backends_used": ["brave", "stackoverflow", "github"]
  },
  "results": [
    {
      "title": "Async in Rust: A comprehensive guide",
      "url": "https://tokio.rs/tokio/tutorial",
      "domain": "tokio.rs",
      "snippet": "Tokio is an asynchronous runtime for the Rust programming language...",
      "score": 0.941,
      "published_at": "2024-11-15T00:00:00Z",
      "source_type": "documentation"
    }
  ]
}

Response fields

Field	Type	Description
`query`	string	The query as processed (post-expansion)
`tier`	string	Detail tier used
`tokens_used`	integer	Tokens consumed from your budget
`sources_count`	integer	Total sources searched across all backends
`duration_ms`	integer	End-to-end latency in milliseconds
`result_id`	string	UUID for this result set
`backends_used`	string[]	Which search backends were queried

results[]

Field	Type	Description
`title`	string	Page title
`url`	string	Full URL of the result
`domain`	string	Hostname of the result
`snippet`	string	Token-budgeted QATBE-extracted content
`score`	float	HyperFusion neural ranking score (0–1)
`published_at`	string?	ISO 8601 publication date if available
`source_type`	string?	Content classification: `documentation`, `blog`, `forum`, `paper`, etc.

Detail tiers

The tier parameter controls the QATBE (Query-Aware Token-Budgeted Extraction) algorithm. Higher tiers extract more content per source but consume more of your token budget:

Tier	Approx tokens	Best for
`key_facts`	~200	Quick answers, chatbot responses, speed-critical apps
`summary`	~1,000	General AI context, RAG pipelines, default choice
`detailed`	~5,000	Thorough research, long-form content generation
`complete`	~20,000	Full document extraction, comprehensive analysis

Backend selection

By default, the Adaptive Backend Selector (ABS) algorithm analyzes your query and selects the optimal combination of backends. You can override this:

json

{
  "query": "tokio select macro explanation",
  "tier": "summary",
  "backends": ["stackoverflow", "github", "brave"]
}

Available backends: brave, google, bing, stackoverflow, github, reddit, searxng

Next steps

Research API →

Deep multi-source research

Scrape API →

URL content extraction