Skip to content

Query and Search

Release binding: v0.1.0-enterprise-ready · AMI ami-010806d4d3445660e · 2026-05-19

Base URL https://<host>:8443. Similarity metric names are cosine, dot, and l2.

Approximate query

POST /v1/query/vector

Top-K similarity search with an external query vector.

curl -sk -X POST https://<host>:8443/v1/query/vector \
  -H "Authorization: Bearer <TENANT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "team-a",
    "data_b64": "<base64-encoded .npy>",
    "k": 10,
    "metric": "cosine"
  }'

POST /v1/query/topk

Top-K most similar entries to a stored key: query_key, k, metric, optional metadata filters.

POST /v1/query/similarity

Core-native similarity between two stored keys: key_a, key_b, metric.

EXACT query with a signed receipt

POST /v1/query/exact

Brute-force top-K against the registered raw corpus, returning results at R@100% by construction along with an ML-DSA-65 (FIPS 204) signed receipt. The receipt is self-verified before the response returns and can be independently verified by any third party.

Request fields: data_b64, namespace, k, metric, optional require_fp64 (force fp64 scoring), optional chunk_rows, optional corpus_name.

Requirements:

  • A raw corpus must be registered for the namespace (see corpus registry); without one the route returns 409.
  • If EXACT-path signing is unavailable the route returns 503.

POST /v1/attestation/verify

Verify a receipt. Anyone holding the receipt can call this route; verification does not require access to the corpus.

Request fields: receipt, optional pinned_public_key_sha256, optional expected_corpus_sha256, optional expected_query_sha256. Pin the public key fingerprint when the verification decision is consequential.

Rerank

POST /v1/rerank and POST /v1/rerank/vector run the second tier explicitly: latent-scan candidates rescored against the SQ8 sidecar.

Route Purpose
POST /v1/search Metadata filter search
POST /v1/search/text Text search
POST /v1/search/hybrid Combined semantic and text search (semantic_metric: cosine, dot, l2)
POST /v1/search/fuzzy Fuzzy matching
POST /v1/search/autocomplete Prefix completion
POST /v1/search/highlight Match highlighting

Feature serving

POST /v1/features/serve serves feature rows for one entity; POST /v1/features/batch serves batches.

Server-side metadata ops

Route Purpose
POST /v1/aggregate Aggregations over stored entries
POST /v1/eval Server-side expression evaluation
POST /v1/append Append to a stored entry
POST /v1/getrange Range reads from a stored entry

Stats

GET /v1/stats reports store and index statistics for the authorized scope.