---
title: "Retrieve matching chunks (no answer)"
method: POST
path: "/org/search/context"
tags: ["Search"]
---

# Retrieve matching chunks (no answer)

`POST /org/search/context`

## Request

- Base URL: `https://apiv2.senso.ai/api/v1`
- URL: `https://apiv2.senso.ai/api/v1/org/search/context`
- Auth: API key in header `X-API-Key`

Runs the same retrieval as `POST /org/search` but returns only the matched chunks — no AI answer is generated. Use this to build your own prompt context; set `neighbor_radius` to include the surrounding chunks of each match. Every chunk carries the `kb_node_id` of its source document, so a passage can be opened in full with `GET /org/kb/nodes/{kb_node_id}`. Each call consumes search credits.

## Headers

- `X-Senso-Signals` string

## Request body

- SearchRequest
  - `query` string, required: The search query. Required and non-empty; there is a maximum length.
  - `max_results` integer: Maximum results to return. Defaults to 5; values ≤ 0 fall back to 5 and values above 20 are capped at 20.
  - `content_ids` string[]: Restrict the search to these content items.
  - `require_scoped_ids` boolean: When true, `content_ids` must be non-empty — the request is rejected with 400 otherwise. Use it to guarantee a scoped search never silently widens.
  - `search_type` string: Retrieval pipeline to use. One of `hybrid` (default), `lexical`, or `vector`. Matching is case-insensitive; an empty or omitted value selects `hybrid`. Any other value is rejected with 400.
  - `neighbor_radius` integer: `/org/search/context` only. Adds up to this many chunks either side of each matched chunk to `results`, marked `inclusion_reason: "neighbor"`, so each match can be read as a passage. Defaults to 0 (matched chunks only); values outside 0–5 are rejected with 400. Total returned text is capped at about 60,000 characters, trimming the farthest neighbours first. Ignored by the other search endpoints, whose answers already include neighbouring chunks.

## Response `200`

The matched chunks.

- SearchContextResponse: Matched chunks only (no AI answer).
  - `query` string, required
  - `search_type` 'hybrid' | 'lexical' | 'vector', required: The retrieval pipeline that produced this response — the scale each result's `score` is on.
  - `results` SearchResultChunk[], required
    - `content_chunk_id` string, uuid, required
    - `content_id` string, uuid, required
    - `kb_node_id` string, uuid, required: The node in the knowledge base tree that the chunk's document lives at. This is the id the `/org/kb/nodes/{kb_node_id}` endpoints take, so a cited chunk can be read in full without a further lookup.
    - `version_id` string, uuid, required
    - `chunk_index` integer, required
    - `chunk_text` string, required
    - `score` number, required: The final relevance score the pipeline ranked and cut on, on the scale named by the response `search_type` (rerank score for hybrid, cosine for vector, document-grain BM25 for lexical). Results from different modes never mix in one response, so scores within a response are comparable.
    - `rank` integer, required: The chunk's 1-based position in the result set.
    - `title` string: The source document's title.
    - `vector_id` string
    - `inclusion_reason` string: Why the chunk is in the result set. Always `matched` on this API.
    - `source_type` 'file' | 'raw' | 'web': The source's kind — `file` (uploaded file), `raw` (raw text/markdown), or `web` (web content).
    - `content_type` string: The source's MIME type (e.g. `application/pdf`, `text/markdown`).
    - `retrieval` ChunkRetrieval: Per-arm retrieval evidence for a chunk. Present on `hybrid` responses only (pure `vector`/`lexical` modes omit it). A key is present only for the arm(s) that found the chunk.
      - `vector` RetrievalArmResult: One retrieval arm's raw score and rank for a chunk.
        - `score` number, required: The arm's own score on the arm's own scale (cosine for vector; document-grain BM25 for lexical).
        - `rank` integer, required: The chunk's 1-based rank in that arm's pool.
      - `lexical` RetrievalArmResult: One retrieval arm's raw score and rank for a chunk.
        - `score` number, required: The arm's own score on the arm's own scale (cosine for vector; document-grain BM25 for lexical).
        - `rank` integer, required: The chunk's 1-based rank in that arm's pool.
  - `total_results` integer, required
  - `max_results` integer, required

## Other responses

- `400`: The request was malformed — a bad path/query parameter or an invalid value.
- `401`: Missing or invalid credentials — supply a valid org API key in the `X-API-Key` header.
- `402`: The organization is out of credits or has reached its spending limit.
- `403`: The API key is authenticated but not permitted to access this resource.

---

[API](https://skmtc.dev/senso/apis/senso-org-api.md) - [All operations](https://skmtc.dev/senso/apis/senso-org-api/llms.txt) - [OpenAPI document](https://skmtc.dev/senso/apis/senso-org-api/revisions/d789b4fcbe84?raw)