Runs a semantic search over the caller org's own knowledge — its wiki pages,…
Runs a semantic search over the caller org's own knowledge — its wiki pages, its agent memories and everything its connectors have synced — and returns…
POST /v1/knowledge/search
| Address | https://api.hanzo.ai/v1/knowledge/search |
| Method | POST |
| Operation | post_knowledge_search |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Runs a semantic search over the caller org's own knowledge — its wiki pages, its agent memories and everything its connectors have synced — and returns the matching passages. This is the RAG entry point: an agent asks "what does this org know about X" and the org's OWN vector namespace answers. The org comes from the validated principal, and both the collection and the payload filter are pinned to it, so cross-tenant retrieval is impossible. An unreachable index returns an honest empty result set with degraded=true, never a 5xx.
Request
4 fields, body application/json (required).
| Field | In | Type | Required | Description |
|---|---|---|---|---|
doctypes | body | string[] | — | DocTypes restricts retrieval to a subset of the indexed knowledge doctypes (kb-page, kb-memory, kb-source). |
limit | body | integer | — | Limit bounds the hits returned. |
project | body | string | — | Project narrows retrieval to one project scope. |
query | body | string | — | Query is the natural-language question. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | searchOut | ok |
200 body — 9 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
degraded | body | boolean | — | Degraded is true when the index was unreachable and this answer is honestly empty rather than wrong — a RAG caller continues with no context instead of failing… |
hits | body | hit[] | — | Hits are the matching passages, most relevant first. |
hits[].doctype | body | string | — | DocType is which kind of knowledge matched: kb-page (a wiki page), kb-memory (a unit of agent memory) or kb-source (a document a connector ingested). |
hits[].name | body | string | — | Name is the document's name in the framework store — the id to read or open it with. |
hits[].project | body | string | — | Project is the project scope the document was saved under. |
hits[].provider | body | string | — | Provider is the connector that ingested the document — github, slack, google or notion. |
hits[].score | body | number | — | Score is the cosine similarity between the query's embedding and the document's, from -1 to 1, higher being closer — the collection is created with Cosine… |
hits[].title | body | string | — | Title is the document's title as it was indexed. |
hits[].url | body | string | — | URL is the document's link back into the app it was ingested from. |
Failure carries the platform error shape — see Errors.
Examples
hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.
import { Configuration, KnowledgeApi } from 'hanzoai';
const api = new KnowledgeApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postKnowledgeSearch({ doctypes: ["<doctypes>"], limit: 0 });from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import KnowledgeApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = KnowledgeApi(client).post_knowledge_search(doctypes=["<doctypes>"], limit=0)cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.KnowledgeAPI.PostKnowledgeSearch(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, knowledge_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = knowledge_api::post_knowledge_search(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.KnowledgeApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new KnowledgeApi(client).postKnowledgeSearch();The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →
curl -X POST https://api.hanzo.ai/v1/knowledge/search \
-H "Authorization: Bearer $HANZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"doctypes": [
"<doctypes>"
],
"limit": 0
}'The door reaches knowledge through the knowledge tool, which names its 9 operations with its own verbs — this one among them, under a name only the door declares. describe explains any of them:
curl -X POST https://api.hanzo.ai/v1/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "describe",
"arguments": {
"op": "list_kb_connectors"
}
}
}'How is this guide?