AlifZetta GSI · API Reference

Route a free-text query to the most appropriate handler and return a structured answer.

Request

POST https://demo.axz.si/api/gsi/answer
Content-Type: application/json

{"query": "petrol price nepal"}

Response

{
  "answer_en":  "⛽ Nepal fuel prices — NOC reference (Kathmandu Valley retail)\n...",
  "grounded":   true,
  "source":     "fuel_handler",
  "match": {
    "id":         "fuel:petrol",
    "title":      "Petrol — NPR 175/litre",
    "category":   "curated_fuel",
    "score":      1800.0,
    "highlighted":"petrol",
    "prices_npr": { "petrol": {"unit":"litre","price":175.00,...}, ... }
  },
  "citations": [{"kind":"curated","source":"Nepal Oil Corporation (noc.org.np)",...}],
  "traversal_trace": ["fuel_handler: petrol"],
  "query_class": "live_handler",
  "compute_ms":  2.4,
  "_cache":      {"hit": false, "key": null},
  "_intent":     {"intent":"fuel","confidence":0.85,...}
}

Structured JSON of today's Nepal news feed (up to 20 items from 13 sources). Refreshed every 30 min.

Live-handler cache stats (hits, misses, hit-rate, active entries, TTL config).

Query volume + P50/P95 latency + cache hit-rate for the rolling window.

Top-N most-frequent queries.

Actionable KB-expansion targets: queries with low confidence + low volume.

Auto-refreshing analytics dashboard (24h volume, top queries, misroutes, coverage, cache stats).

One call returns an AlifZetta engine answer (text, sources, confidence, source tier) plus web results (title, url, snippet). English and Nepali. Requires a partner key with scope search (or full) in the X-Partner-Key header. Keys are issued by padam@axz.si.

Server to server only. Call this from your backend. Never ship the key in a web page or a mobile app; browser CORS is not enabled for this endpoint.

Request

POST https://demo.axz.si/api/partner/search
X-Partner-Key: <your search key>
Content-Type: application/json

{"q": "who is the prime minister of Nepal", "lang": "auto", "limit": 5, "include_web": true, "safe": true}

GET takes the same fields as query parameters, for example /api/partner/search?q=capital%20of%20nepal&include_web=false.

Response

{
  "ok": true,
  "query": "who is the prime minister of Nepal",
  "lang": "en",
  "answer": {
    "text": "As of 2026, the Prime Minister of Nepal is Balen Shah, sworn in on 27 March 2026. ...",
    "sources": [{"title": "balen shah", "url": null}],
    "confidence": 0.99,
    "engine": "alifzetta-gsi",
    "tier": "canonical_query",
    "grounded": true,
    "status": "ok"
  },
  "web": [
    {"title": "Prime Minister of Nepal", "url": "https://en.wikipedia.org/wiki/Prime_Minister_of_Nepal", "snippet": "The Prime Minister of Nepal is the head of government ..."}
  ],
  "status": {"answer": "ok", "web": "ok"},
  "took_ms": 611,
  "request_id": "srch_2b6a442d36b1"
}

Each section reports its own status (ok, empty, timeout, error, skipped). If one source fails the other is still returned. Budgets: answer about 12 s, web about 8 s.

DTL v0.1 output

Send Accept: application/dtl or add ?format=dtl. The body is a signed DTL v0.1 document with header @DTL v0.1 | dom:dtSRCH | C0 | cs:<sha256> | prf:partner-search | ts:.... dtSRCH is a custom domain code (DTL v0.1 has no search domain); C0 because search results are public. The checksum is also in the X-DTL-CS response header.

Errors and quotas

Every response carries X-Request-Id. Successful responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Quotas are per key per clock hour; nginx also applies a per-IP burst limit.

Example

curl -sS -X POST https://demo.axz.si/api/partner/search \
  -H "X-Partner-Key: $AZ_SEARCH_KEY" -H 'Content-Type: application/json' \
  -d '{"q":"नेपालको प्रधानमन्त्री को हुन्?","lang":"ne","limit":3}' | jq