---
title: "Find matching content items"
method: POST
path: "/org/search/content"
tags: ["Search"]
---

# Find matching content items

`POST /org/search/content`

## Request

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

Runs the retrieval and returns only the distinct documents that matched — no chunks, no AI answer. Each item carries the document's `kb_node_id` alongside its `content_id` and title, so a match can be read, renamed, moved or deleted through the `/org/kb/nodes/{kb_node_id}` endpoints without a further lookup. Use this to discover which documents are relevant. 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 distinct content items that matched.

- SearchContentResponse: The distinct content items that matched (no chunks, no answer).
  - `query` string, required
  - `search_type` 'hybrid' | 'lexical' | 'vector', required: The retrieval pipeline that produced this response.
  - `contents` SearchContentItem[], required
    - `content_id` string, uuid, required
    - `kb_node_id` string, uuid, required: The document's node in the knowledge base tree. This is the id the `/org/kb/nodes/{kb_node_id}` endpoints take, so a match can be read, renamed, moved or deleted without a further lookup.
    - `title` string
  - `total` 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)