---
title: "Semantic Search"
method: POST
path: "/search"
tags: ["Search"]
---

# Semantic Search

`POST /search`

## Request

- Base URL: `https://api.getmetacognition.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getmetacognition.com/search`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/metacognition/apis/tex-api/docs/search/post.ts> (a function with typed inputs; its response is checked against the schema)

Semantic vector search over stored memories.

Embeds the query text, runs HNSW nearest-neighbour search, and returns
ranked text chunks with similarity scores. No planner LLM call.

Scoped to the current tenant (org_id + user_id).

## Request body

- SearchRequest: Request for semantic vector search.
  - `query` string, required: Natural language search query
  - `top_k` integer: Number of results to return
  - `min_score` number, nullable: Minimum similarity score (0-1)
  - `label` string, nullable: Filter by node label/type
  - `metadata_filter` object, nullable: Key-value metadata filters

## Response `200`

Successful Response

- SearchResponse: Response from semantic search.
  - `results` SearchResultItem[]
    - `id` string, required: Node ID (UUID)
    - `score` number, required: Similarity score (0-1)
    - `text` string, required: Matched text content
    - `type` string, required: Node type/label
    - `metadata` object, nullable: Node metadata. Engine-hydrated rendering keys (when available): text_source (vector|evidence|chunk|entity_name|none), entity_name, entity_type, source_chunk_id, source_document_id
    - `inferences` string[], nullable: Inference text attached to the hit's entity (additive; null when none)
  - `query_embedding_ms` integer: Time to embed query (ms)
  - `search_ms` integer: Time to search HNSW index (ms)

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/metacognition/apis/tex-api.md) - [All operations](https://skmtc.dev/metacognition/apis/tex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metacognition/apis/tex-api/revisions/3bef47e50f2e?raw)