Documentation
POST /v1/research
Bundles search + page reading into one counted call and returns an evidence pack: ranked sources, their excerpts, trust signals, and a 0–1 confidence score. Write your answer from sources[].excerpt and signals — that is the agent's job, not ours.
Depth modes and hard budgets
- fast — one search k=8, no page reads, returns snippets only (excerpt=null). Budget 8s.
- balanced — one search k=10, reads the best 4 sources in parallel. Budget 20s.
- deep — one search k=16, reads the best 6. Budget 40s.
- quality retry — at any depth: an official-intent question whose first pass lacks a trusted rank-1 gets one extra pass from the same budget, kept only if better (trusted top-1 > trusted count). Response: attempts:1|2.
Budget exceeded → HTTP 200 with partial:true and partialReason:"time_budget" — whatever was gathered is returned; 504 is never emitted for the budget.
Confidence formula
0–1 signal quality score — arithmetic over the trust/read signals, not a model judgment.
confidence
base = 0.35*trustedTop1 + 0.25*min(trustedCount,3)/3
+ 0.20*(readOk/(readOk+readFailed)) + 0.20*min(distinctDomains,3)/3
coverage = best-effort → cap 0.55
read-failure ratio > 0.5 → −0.10
rounded to 2 decimals, clamped to [0,1]What v1 does not do
- No written answer — the calling agent writes from sources[].excerpt and signals.
- No model or LLM — everything here is retrieval, extraction, and arithmetic.
- No claims extraction — excerpts are raw page text.
- No contradiction detection — signals are counts, not judgments.
Search + read in one counted call. Returns an evidence bundle — ranked sources with excerpts, trust signals, and a 0–1 confidence score — for the calling agent to write from. One request = one quota unit; internal reads are never billed.
Request
| Field | Type | Description | |
|---|---|---|---|
question | string (3..1000) | required | The research question (3–1000 chars, any language). |
depth | 'fast' | 'balanced' | 'deep' | optional | fast: one search, no reads (8s) · balanced: search + best 4 reads (20s) · deep: search + best 6 reads (40s). Official-intent questions get one quality retry from the same budget at any depth — the response carries attempts:1|2. Default balanced. |
lang | 'auto' | 'ar' | 'en' | optional | auto (default), ar, or en — forwarded to the search router. |
maxSources | integer (1..10) | optional | Override the depth default (fast 3, balanced 4, deep 6; max 10). |
Example
curl -X POST https://agw.orcanox.xyz/v1/research \ -H "Authorization: Bearer agw_…" \ -H "Content-Type: application/json" \ -d '{"question":"شروط تأشيرة زيارة عائلية للسعودية"}'
import requests r = requests.post("https://agw.orcanox.xyz/v1/research", headers={"Authorization": "Bearer agw_…"}, json={"question":"شروط تأشيرة زيارة عائلية للسعودية"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/v1/research", { method: "POST", headers: { "Authorization": "Bearer agw_…", "Content-Type": "application/json" }, body: JSON.stringify({"question":"شروط تأشيرة زيارة عائلية للسعودية"}) }); console.log(r.status, await r.json());
Response
json
{
"question": "شروط تأشيرة زيارة عائلية للسعودية",
"depth": "balanced",
"partial": false,
"coverage": "official",
"confidence": 0.87,
"signals": {
"trustedTop1": true,
"trustedCount": 3,
"distinctDomains": 5,
"readOk": 4,
"readFailed": 0,
"officialRetried": false
},
"sources": [
{
"rank": 1,
"url": "https://visa.mofa.gov.sa/…",
"title": "Family Visit Visa — MOFA",
"domain": "visa.mofa.gov.sa",
"trusted": true,
"snippet": "…",
"excerpt": "First ~1200 chars of clean page text…",
"method": "http",
"readOk": true,
"tookMs": 812
}
],
"routeAttempts": [
{
"route": "searxng",
"status": "ok",
"ms": 640
}
],
"tookMs": 5120,
"traceId": "rq_…"
}Errors
| Status | code | Example |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"question is required"} |
| 502 | fetch_failed | {"code":"fetch_failed","message":"all search routes failed"} |