---
title: "Semantic search contexts"
method: GET
path: "/contexts/semantic-search"
tags: ["Contexts"]
---

# Semantic search contexts

`GET /contexts/semantic-search`

## Request

- Base URL: `https://apigcp.trynia.ai/v2`
- URL: `https://apigcp.trynia.ai/v2/contexts/semantic-search`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/nozomio-labs/apis/nia-ai-api/docs/contexts/semantic-search/get.ts> (a function with typed inputs; its response is checked against the schema)

Vector + BM25 hybrid search over contexts. Returns relevance scores and highlights.

## Query parameters

- `q` string, required: Search query
- `limit` integer: Number of contexts to return
- `include_highlights` boolean: Include match highlights
- `workspace_filter` string, nullable: Filter by specific workspace name

## Response `200`

Successful Response

- ContextSemanticSearchResponse: Response for semantic search in contexts.
  - `results` object[]: Search results with scores
  - `search_query` string, required: The search query used
  - `search_metadata` ContextSemanticSearchMetadata, required: Metadata for semantic search.
    - `search_type` string: Type of search performed
    - `total_results` integer: Number of results
    - `vector_matches` integer: Number of vector matches
    - `mongodb_matches` integer: Number of MongoDB matches
  - `suggestions` ContextSemanticSearchSuggestions, required: Suggestions from semantic search.
    - `related_tags` string[]: Related tags
    - `workspaces` string[]: Related workspaces
    - `tips` string[]: Search tips

## Other responses

- `422`: Validation Error

## Changes

- **2026-03-10** `264ed942dacc`: 1 warning, 1 info
  - removed the optional property `search_metadata/text_matches` from the response with the `200` status
  - added the optional property `search_metadata/mongodb_matches` to the response with the `200` status
- **2026-02-28** `7e426dce5dda`: 1 warning, 3 info
  - removed the optional property `search_metadata/mongodb_matches` from the response with the `200` status
  - api tag `Contexts` added
  - api tag `Context Sharing` removed
  - added the optional property `search_metadata/text_matches` to the response with the `200` status
- **2026-02-19** `c41dcb6ac8f7`: 2 info
  - api tag `Context Sharing` added
  - api tag `Contexts` removed
- **2026-02-14** `5b3db391b9ea`: 3 info
  - api tag `Contexts` added
  - api tag `v2-api` removed
  - api tag `v2-api-contexts` removed

[Operation history](https://skmtc.dev/nozomio-labs/apis/nia-ai-api/changes/contexts/semantic-search/get.md)

---

[API](https://skmtc.dev/nozomio-labs/apis/nia-ai-api.md) - [All operations](https://skmtc.dev/nozomio-labs/apis/nia-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nozomio-labs/apis/nia-ai-api/revisions/dbb602a3ef17?raw)