HANAI API
Reference
Transform raw search results into structured @entities, hierarchical folder paths, and trust scores. Every request runs through a 6-step pipeline — fully hosted, no setup required.
Get an API Key
HANAI is a hosted API — no installation, no servers to manage. Get your key in under a minute:
List your application
Head to the Developer Portal and sign in with Google.
Generate your key
Click Generate API Key. Your key looks like hnai_abc123... — copy it immediately.
Attach to every request
Pass the key via the X-API-Key header on all protected endpoints.
Quick Start
Make your first structured search in under a minute.
curl -X POST https://hanai-api.onrender.com/search \ -H "X-API-Key: hnai_your_key_here" \ -H "Content-Type: application/json" \ -d '{"query": "buy running shoes", "region": "auto"}'
const res = await fetch('https://hanai-api.onrender.com/search', { method: 'POST', headers: { 'X-API-Key': 'hnai_your_key_here', 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'buy running shoes', region: 'auto' }) }); const data = await res.json();
import requests data = requests.post( 'https://hanai-api.onrender.com/search', headers = { 'X-API-Key': 'hnai_your_key_here' }, json = { 'query': 'buy running shoes', 'region': 'auto' } ).json()
Authorization
Protected endpoints require your API key in the X-API-Key request header.
@Entities Core Concept
Every domain maps to a canonical @entity. Multiple regional or subdomain variants collapse into one stable identity — so your code never needs to handle duplicates.
# Regional variants → single entity amazon.com ─┐ amazon.in ─┤ → @amazon amazon.co.uk ─┘ # Subdomains → entity + service attribute maps.google.com → @google (service: maps) youtube.com → @youtube (service: video)
Folder System Core Concept
Each entity gets a structured hierarchical path following the pattern @entity / region / service / category, making results navigable like a filesystem.
@amazon / india / fashion @google / global / maps @youtube / global / video @wikipedia / global / education @myntra / india / fashion
Trust Engine Core Concept
Six signals combine into a trust score. Results are ranked trust-first — dangerous entries never surface above verified ones.
| Label | Score | Meaning |
|---|---|---|
| Verified | ≥ 0.88 | Known, established entity with consistent history |
| Safe | ≥ 0.70 | Appears legitimate, no suspicious signals |
| Unverified | ≥ 0.50 | Unknown origin but nothing flagged |
| Suspicious | ≥ 0.30 | Unusual domain patterns or signals detected |
| Dangerous | < 0.30 | Fake or malicious entity detected |
Intent Engine Core Concept
Every query is classified before fetching. Intent type affects ranking weights and minimum trust thresholds applied to results.
transactional → "buy shoes", "order pizza" navigational → "amazon login", "youtube" informational → "how does X work" local → "restaurants near me"
POST /search
The main pipeline. Fetches from multiple sources in parallel, deduplicates, resolves @entities, builds folder paths, scores trust, and returns ranked structured results.
Request Body
| Field | Type | Description |
|---|---|---|
| query req | string | Natural language search query |
| region | string | auto (default), in, us, uk, ... |
| tab | string | web (default), videos, images, news |
{
"query": "buy running shoes",
"region": "auto",
"tab": "web"
}
Responses
GET /entity
GET /entity # list all known entities GET /entity/:id # e.g. GET /entity/amazon
GET /trust
GET /trust/amazon
Response Schema
Every POST /search response returns the same structured envelope:
{
"intent": { "type": "transactional", "confidence": 0.92 },
"tab": "web",
"results": [
{
"entity": "@amazon",
"path": "@amazon/india/fashion",
"display": "@amazon / india / fashion",
"folders": [
{ "type": "region", "value": "india" },
{ "type": "category", "value": "fashion" }
],
"trust": {
"score": 0.91,
"label": "Verified",
"confidence": 0.95
},
"source_count": 4,
"rank": 1
}
],
"meta": {
"query": "buy running shoes",
"region": "in",
"duration_ms": 312,
"result_count": 3,
"raw_result_count": 18
}
}
Rate Limits
Limits are per API key and reset daily at midnight UTC.
Error Codes
| Status | Code | Description |
|---|---|---|
| 401 | MISSING_KEY | No X-API-Key header provided |
| 403 | INVALID_KEY | Key not found or has been revoked |
| 429 | DAILY_LIMIT | 50 request daily limit reached |
| 429 | RATE_LIMIT | Too many requests per minute |
| 400 | EMPTY_QUERY | Query field missing or empty |
| 500 | SERVER_ERROR | Internal pipeline error |
JavaScript SDK
import HANAI from 'https://cdn.jsdelivr.net/npm/hanai-sdk/hanai.min.js'; const client = new HANAI({ baseURL: 'https://hanai-api.onrender.com', apiKey: 'hnai_your_key_here' }); const results = await client.search('buy shoes', { region: 'india' }); const trust = await client.trust('amazon'); const entity = await client.entity('google');
Python SDK
from hanai import HANAI client = HANAI( base_url = 'https://hanai-api.onrender.com', api_key = 'hnai_your_key_here' ) results = client.search('buy shoes', region='india') trust = client.trust('amazon') entities = client.entities()