Search Knowledge

Select a knowledge base

Register a Knowledge with contents_db on AgentOS, an Agent or a Team. Read the actual generated ID from GET /config under knowledge.knowledge_instances; use that knowledge_id in the request's selector. It is not an arbitrary Knowledge.id. A selector is required when multiple instances make the request ambiguous (400); no configured knowledge base returns 503. If both selectors are supplied, knowledge_id takes precedence over db_id.

Ingestion and search also require suitable readers, vector storage, an embedder where needed, and their dependencies and credentials. See Knowledge.

Content access

Scoped callers can read their own and shared content; other-owned records return 404. JWT user scoping requires user isolation, while non-admin service-account PAT users always self-scope. A scoped caller cannot modify, refresh or delete shared content (403). Authentication alone does not enable JWT user isolation.

Search window and results

Put selection and search options in the JSON request body:

{"knowledge_id":"returned-knowledge-id","query":"How do sessions work?","max_results":20,"meta":{"page":1,"limit":10}}

max_results limits retrieved candidates before pagination. Response meta.total_count counts those candidates, not all matching documents in the corpus. vector_db_ids validates against the selected knowledge base's vector backend; it does not fan out across arbitrary stores.

No matches returns 200 with data: [], despite the generated 404 description. Search types and metadata filters must be supported by the selected backend. Vector/hybrid search may need embedding credentials.

curl --request POST 'https://example.com/knowledge/search' \  --header 'Content-Type: application/json' \  --data-raw '{"query":"string"}'

{  "data": [    {      "id": "doc_123",      "content": "Jordan Mitchell - Software Engineer with skills in JavaScript, React, Python",      "name": "cv_1",      "meta_data": {        "page": 1,        "chunk": 1      },      "usage": {        "total_tokens": 14      },      "reranking_score": 0.95,      "content_id": "content_456"    }  ],  "meta": {    "page": 1,    "limit": 20,    "total_pages": 2,    "total_count": 35  }}

{  "detail": "string",  "error_id": "string",  "error_type": "string"}

{  "detail": "string"}

{  "detail": "string",  "error_id": "string",  "error_type": "string"}