Web search API

1. 1

   Discovery

   Official search APIs return candidate URLs only. Their titles, snippets and ranking are discarded.

2. 2

   Fetch

   HoloSignal fetches each page itself: robots-aware, public pages only.

3. 3

   Rank

   BM25 relevance with Unicode word segmentation (Thai, Japanese and Chinese work), domain class, freshness and page quality. Near-duplicates are marked with dupOf.

4. 4

   Answer

   A generated answer when the model layer is available, otherwise an extractive answer built from the best passages. Both cite results by position.

• HoloSignal API keys (oxy_live_…, oxy_test_…) as a bearer token, or
• a Sansa service key (sa_rt_…) through Sansa Auth. Send x-sansa-tenant-id and, for metered actions, x-sansa-billing-profile-id. Actions: oxysignal.search.run, oxysignal.fetch.run, oxysignal.context_packs.query (metered) and oxysignal.runs.read.
• Every create call needs an Idempotency-Key. Reusing a key with a different body returns 409 IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST.

?wait= accepts seconds (10, 10s) or milliseconds (1500ms), capped at 25 seconds. When the run finishes in time the response is 200 with the search result. If it isn't finished in time the response is the usual 202 with run_id, status_url and Retry-After: 2; poll GET /api/v1/runs/{id}, whose output_json.search has the same results and answer. Without ?wait= every new search returns 202.

A search that fails within the wait returns 422 with the same body plus error; when every page was filtered out, error.message is NO_RESULTS_MATCH_FILTERS. Full schemas: SearchRequest, SearchResponse and SearchResult in /openapi.json.

POST /api/v1/search?wait=10
Authorization: Bearer oxy_live_…
Idempotency-Key: 4f1c…
Content-Type: application/json

{
  "query": "JLPT N5 official test format",
  "lang": "en", "country": "JP", "freshness": "1y",
  "includeDomains": ["jlpt.jp"], "domainMode": "boost",
  "domainClasses": ["gov", "edu", "official"],
  "safeSearch": "strict", "maxResults": 10,
  "content": "markdown", "answer": true,
  "budget": { "maxUnits": 20 }
}

Hints go to discovery where supported; HoloSignal enforces every filter itself on the fetched pages.

Languages: Wikipedia discovery covers en, nb, sv, da, de, fr, es, ar, zh, hi, ja, pt and th; open-web discovery covers every language, with HoloSignal's own language filter applied. Detection covers Thai, Japanese, Arabic, Hindi, Korean, Chinese and Cyrillic by script, and en, de, fr, es, pt, sv, da and nb by vocabulary.

Schema holosignal.search-results/v1. answer.citations are 0-based positions in results; answer.method is extractive or generated; answer is null when answer: false. usage.units is what the search charged, latencyMs its run time, and statusUrl the durable run resource.

{
  "runId": "run_…", "status": "completed", "schema": "holosignal.search-results/v1",
  "fetch": { "status": "ok" },
  "answer": { "text": "…", "citations": [0, 2], "method": "extractive" },
  "results": [{
    "rank": 1, "url": "…", "canonicalUrl": "…", "title": "…",
    "snippet": "…", "content": "…", "lang": "en",
    "publishedAt": "2025-…", "fetchedAt": "…", "fetched": true,
    "domainClass": "official", "score": 0.83, "relevance": 0.91,
    "dupOf": null, "license": null, "sourceId": "src_…", "snapshotId": "snap_…"
  }],
  "usage": { "units": 18 }, "latencyMs": 7400, "statusUrl": "/api/v1/runs/run_…"
}

Result fields

Metadata is read from each page's HTML: JSON-LD, Open Graph and <time> tags for dates, and rel=license and Creative Commons links for licences. publishedAt and license are null only when the page doesn't declare them.

fetch.status is ok when HoloSignal fetched pages, or unavailable with a reason when page fetching could not run. The search then degrades instead of failing: results carry the discovered URLs only, with fetched: false, no title, snippet, content or language, and answer: null. Only URL-level filters (includeDomains, excludeDomains, domainMode, domainClasses) apply, because language, date and content checks need the page. Check fetch.status before relying on snippets or answers.

{
  "fetch": { "status": "unavailable", "reason": "Page fetching is disabled on this deployment." },
  "answer": null,
  "results": [{
    "rank": 1, "url": "https://www.jlpt.jp/e/guideline/testsections.html",
    "canonicalUrl": "https://www.jlpt.jp/e/guideline/testsections.html",
    "title": null, "snippet": "", "lang": null, "publishedAt": null, "fetchedAt": null,
    "fetched": false, "domainClass": "official", "score": 1, "relevance": 0,
    "dupOf": null, "license": null, "sourceId": "", "snapshotId": ""
  }]
}

• canonicalUrl: from the page, else the final URL.
• dupOf: set when the normalized URL matches (tracking parameters, www. and index.html removed) or the text is a near-duplicate (SimHash, 3 bits or fewer different). Originals come first.
• score (0–1): overall rank. relevance (0–1): query match only.