API Reference
Research API
The Research API runs a full multi-step investigation: it searches across backends, extracts content from top sources, synthesizes findings with citations, and returns a structured research report — all in a single request.
The research pipeline typically takes 10–45 seconds depending on complexity. Results are substantially deeper than the Search API. Token consumption is higher.
POST/v1/research
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Research question. Max 1,000 characters. |
max_sources | integer | No | Sources to investigate deeply. Range: 1–20. Default: 8. |
token_budget | integer | No | Total token budget. Range: 1,000–50,000. Default: 8,000. |
citation_style | string | No | apa, mla, chicago, inline, none. Default: inline. |
depth | string | No | shallow (fast), standard (default), deep (thorough, slower). |
include_evidence_graph | boolean | No | Include source agreement/disagreement analysis. Default: false. |
language | string | No | BCP-47 output language. Default: en. |
freshness | string | No | Filter sources by date: week, month, year. |
Example request
research.sh
curl -X POST https://api.hypersearchx.zuhabul.com/v1/research \
-H "Authorization: Bearer hsx_your_key" \
-H "Content-Type: application/json" \
-d '{
"query": "Compare vector databases for production use: pgvector vs Pinecone vs Weaviate vs Qdrant",
"max_sources": 10,
"citation_style": "inline",
"depth": "deep",
"freshness": "year"
}'Response
response.json
{
"meta": {
"query": "Compare vector databases for production use...",
"depth": "deep",
"tokens_used": 11482,
"sources_searched": 47,
"sources_used": 10,
"duration_ms": 28340,
"result_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"report": "## Vector Database Comparison for Production\n\nVector databases have emerged as a critical infrastructure component for AI applications [1]. After analyzing 10 authoritative sources, here is a comprehensive comparison:\n\n### pgvector\npgvector extends PostgreSQL with vector similarity search capabilities [2]...",
"citations": [
{
"id": 1,
"title": "Vector Databases: A Comprehensive Guide",
"url": "https://www.pinecone.io/learn/vector-database/",
"domain": "pinecone.io",
"accessed_at": "2025-06-20T14:30:00Z"
}
],
"sources": [
{
"title": "Vector Databases: A Comprehensive Guide",
"url": "https://www.pinecone.io/learn/vector-database/",
"score": 0.923,
"contribution": "primary"
}
],
"findings": [
{
"claim": "pgvector is best for teams already using PostgreSQL",
"confidence": 0.91,
"supporting_sources": [1, 2, 4],
"contradicting_sources": []
}
]
}Response fields
meta
| Field | Description |
|---|---|
sources_searched | Total URLs found across backends |
sources_used | Sources deeply extracted and included in report |
duration_ms | End-to-end processing time (can be 10–45s for deep) |
report
Markdown-formatted research synthesis with inline citations.
findings[]
| Field | Description |
|---|---|
claim | Synthesized finding or conclusion |
confidence | 0–1 confidence based on source agreement |
supporting_sources | Citation IDs that support this claim |
contradicting_sources | Citation IDs that contradict this claim |
Evidence graph
Enable include_evidence_graph: true to get a detailed analysis of source agreement and contradictions:
json
{
"query": "Is Rust faster than Go for web servers?",
"include_evidence_graph": true,
"depth": "deep"
}Citation styles
| Style | Example |
|---|---|
inline | ...is widely used [1]... |
apa | Smith, J. (2024). Title. Journal, 1(1). |
mla | Smith, John. "Title." Journal 1.1 (2024). |
chicago | Smith, John. "Title." Journal 1, no. 1 (2024). |
none | No citations appended |
TypeScript example with streaming
research.ts
async function research(query: string) {
const res = await fetch("https://api.hypersearchx.zuhabul.com/v1/research", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.HSX_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
query,
max_sources: 8,
citation_style: "inline",
depth: "standard",
}),
});
if (!res.ok) {
const err = await res.json();
throw new Error(`Research API error: ${err.error.message}`);
}
const data = await res.json();
console.log(data.report); // Markdown report
console.log(data.citations); // Cited sources
console.log(data.findings); // Synthesized claims
return data;
}