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.
POST /v1/research api-key · search #

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

FieldTypeDescription
questionstring (3..1000)requiredThe research question (3–1000 chars, any language).
depth'fast' | 'balanced' | 'deep'optionalfast: 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'optionalauto (default), ar, or en — forwarded to the search router.
maxSourcesinteger (1..10)optionalOverride 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":"شروط تأشيرة زيارة عائلية للسعودية"}'

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

StatuscodeExample
400bad_request{"code":"bad_request","message":"question is required"}
502fetch_failed{"code":"fetch_failed","message":"all search routes failed"}