---
title: "Search an agent's knowledge base"
method: POST
path: "/api/v1/agents/{agent}/search"
---

# Search an agent's knowledge base

`POST /api/v1/agents/{agent}/search`

Performs a semantic search over an agent's knowledge base and returns a ranked,
`kind`-discriminated list of matching items.

Two item kinds may appear in `data`:

- `"chunk"` — chunk-level results from the agent's context store. Present for all agents.
- `"document"` — document-level results. Present only when the agent has an active
  `archastro/knowledge` installation.

Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to
be comparable across kinds, then merged into a single ranked list. On a relevance tie,
chunks appear before documents. The total number of results is capped at `max_results`
across both kinds.

Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and
full-text search; `"vector"` and `"fulltext"` select each strategy independently.

## Path parameters

- `agent` string, required

## Request body

- object
  - `max_results` integer — Maximum total results to return across all kinds. Chunks and documents are ranked together and the list is capped at this value. Defaults to `20`; maximum is `100`.
  - `mode` string — Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`.
  - `query` string, required — Natural-language search query used to retrieve relevant knowledge items.
  - `recency_days` integer — When set, restricts results to items indexed within the last N days.
  - `source_types` string[] — Array of source-type slugs used to filter chunk results, e.g. `["web", "file"]`. Omit to include all source types.

## Response `200`

Successful response

- object — Knowledge search results for the specified agent.
  - `data` union[], required — Ranked list of matching knowledge items. Each item is a `kind`-discriminated union — either `"chunk"` (always present) or `"document"` (present only when the agent has an active `archastro/knowledge` installation). Sorted by relevance descending; capped at `max_results` total across both kinds.
    - union — A discriminated union representing a single result from a knowledge search. The `kind` field identifies the variant: `"chunk"` for a chunk-level result (see `KnowledgeSearchResult`) or `"document"` for a document-level result (see `DocumentSearchResult`).
      - object — A single chunk returned by a knowledge search query. Represents an indexed content item matched against the search terms.
        - `content` string — Normalized plain-text content of the matched chunk.
        - `content_type` string — MIME type of the content, e.g. `"text/plain"` or `"text/html"`.
        - `created_at` string, date-time — When this item was indexed into the knowledge base (ISO 8601).
        - `id` string, required — Context item ID (`cim_...`).
        - `kind` 'chunk', required — Result variant discriminator. Always `"chunk"` for this object type.
        - `metadata` object — Arbitrary key-value metadata attached to this item by the source connector.
        - `raw_content` object — Raw content payload as stored by the source connector, before normalization.
        - `type` string — Type identifier of the parent knowledge source (e.g. `"gmail"`, `"github_activity"`). Returns `"unknown"` when the source association is not loaded.
      - object — A single document-level result returned by a knowledge search query. Includes a short preview snippet and content statistics alongside the document's metadata.
        - `id` string, required — Document ID (`cdo_...`).
        - `kind` 'document', required — Result variant discriminator. Always `"document"` for this schema; use this field to distinguish document results from other `KnowledgeResult` variants.
        - `metadata` object — Arbitrary key-value metadata attached to the document. `null` if no metadata has been set.
        - `snippet` string — Leading 300-character preview of the document's text content, trimmed of surrounding whitespace. Truncated with an ellipsis when the full content exceeds the limit.
        - `title` string — Title of the document as stored in the knowledge base. `null` if the document has no title.
        - `total_lines` integer — Total number of lines in the document's text content. `0` for empty documents.
        - `total_size` integer — Total byte size of the document's text content encoded as UTF-8. `0` for empty documents.

## Other responses

- `401` — Unauthorized
- `404` — Agent not found
- `422` — Invalid parameters

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/versions/a8772b442f86/schema)