Search

Answers a natural-language query with SKIM's multi-hop reasoning loop: read the most relevant passage, absorb it, find the next passage that matters given what was just read — hop by hop, until the learned sufficiency head says "enough." Returns supporting passages, a calibrated confidence, hops_used, an optional trace, and server-measured latency_ms. Requires Authorization: Bearer <key>.

Request body

Response 200

Returns a SearchResult.

curl -X POST https://api.rekall.sh/v1/stores/contracts/search \
  -H "Authorization: Bearer $REKALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "which supplier contract conflicts with the new policy?",
    "max_hops": 6,
    "max_results": 5,
    "return_trace": true,
    "filter": { "team": "procurement" }
  }'

const result = await store.search(
  "which supplier contract conflicts with the new policy?",
  { maxHops: 4, maxResults: 5, trace: true, filter: { team: "procurement" } },
);

result = store.search(
    "which supplier contract conflicts with the new policy?",
    max_hops=4, max_results=5, trace=True, filter={"team": "procurement"},
)

{
  "passages": [
    { "doc_id": "supplier_a", "text": "…Supplier A payment terms are net-90 as amended in §4.2…",
      "score": 0.92, "hop": 1, "metadata": { "source": "supplier_a.pdf" } },
    { "doc_id": "policy_2026", "text": "…all supplier payment terms must not exceed net-60…",
      "score": 0.81, "hop": 2, "metadata": { "source": "policy_2026.md" } }
  ],
  "confidence": 0.87,
  "hops_used": 2,
  "trace": [
    { "hop": 1, "doc_id": "supplier_a",  "why": "matches query" },
    { "hop": 2, "doc_id": "policy_2026", "why": "conflict found, given hop 1" }
  ],
  "latency_ms": 4.2,
  "engine": "skim-v1"
}

Notes

• max_hops is a ceiling, not a target. hops_used reports the actual effort; the engine stops early when the sufficiency head is satisfied. Leaving max_hops at 4 is right for most corpora.
• return_trace is nearly free — enable it freely for explainability and debugging.
• filter is metadata equality — every key/value pair must match for a document to be considered.

Errors: 400 invalid_request (e.g. max_hops out of [1,8]), 404 store_not_found, 401 unauthorized, 429 rate_limited. See Errors.