Search an agent's knowledge base

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.

post/api/v1/agents/{agent}/search

Path parameters

agentstring required

ID (agi_...) or lookup_key of the agent whose knowledge base to search.

Request body

max_resultsinteger

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.

modestring

Retrieval strategy. One of "hybrid" (default), "vector", or "fulltext".

querystring required

Natural-language search query used to retrieve relevant knowledge items.

recency_daysinteger

When set, restricts results to items indexed within the last N days.

source_typesstring[]

Array of source-type slugs used to filter chunk results, e.g. ["web", "file"]. Omit to include all source types.

Example request

{
  "max_results": 1,
  "mode": "string",
  "query": "string",
  "recency_days": 1,
  "source_types": [
    "string"
  ]
}

Response

Successful response

Example response

{
  "data": []
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.