API/AI Gateway/Semantic Vector Search

Semantic Vector Search

GET/v1/ai/{project_id}/search

Performs high-performance semantic similarity queries across vector namespaces with tunable thresholds and top-k limits.

search.tstypescript

const { data: matches } = await aura.ai.semanticSearch(
  'What are the encryption requirements?',
  'legal-docs',
  { threshold: 0.8, top_k: 5 }
)

for (const match of matches ?? []) {
  console.log(`[${match.similarity.toFixed(2)}] ${match.content}`)
}

200.jsonjson

{
  "data": [
    {
      "id": "c3d4e5f6-7890-4abc-def1-234567890abc",
      "content": "All data at rest must be encrypted using AES-256-GCM or native Vault Transit KEKs...",
      "metadata": { "section": "compliance" },
      "similarity": 0.895
    }
  ]
}

Query

Query Parameters

Parameter	Type	Required	Description
`query`	`string`	yes	Search phrase or natural language query.
`namespace`	`string`	yes	Target partition namespace to query against.
`top_k`	`number`	no	Maximum documents returned (default `5`, max `100`).
`threshold`	`number`	no	Minimum cosine similarity threshold from `0.0` to `1.0` (default `0.7`).

Performance

Dynamic HNSW Tuning

Info

The search endpoint dynamically sets PostgreSQL's hnsw.ef_search variable based on requested top_k ((top_k * 4).max(64)), guaranteeing high recall even when filtering post-index candidates.

v1.0 · revised Oct 31, 2026
↗ OpenAPI spec↗ GitHub

← PREVIOUS

Embeddings

NEXT →

RAG query & ingest