Knowledge

Knowledge holds three things people usually keep apart: the pages your team writes, the memories your agents accumulate, and the documents pulled in from tools you already use. They share one store, one index, and one graph, which is what makes a single search answer questions that span all three.

What is in it

Pages, memories, and sources are vector-indexed. Connectors and links are structure, not content.

Search it

One call searches all three indexed kinds at once — this is the retrieval entry point an agent uses.

curl -X POST https://api.hanzo.ai/v1/kb/search \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "how do we handle refunds past 30 days" }'

{
  "hits": [
    { "doctype": "kb-page", "name": "refund-policy", "title": "Refund policy", "score": 0.83 },
    { "doctype": "kb-source", "name": "sl-8821", "title": "#support thread", "provider": "slack", "url": "https://...", "score": 0.71 }
  ]
}

query is required. Narrow with project, cap with limit, or restrict doctypes to some of kb-page, kb-memory, kb-source — the filter can only narrow that set, never widen it.

Indexing and querying use the same embedding model, and each org's vectors live in their own collection with an org filter applied on top of it.

If the vector store is unreachable, a search returns degraded: true with no hits rather than an error — and a write still succeeds, because indexing failing must never block someone saving a page.

Import an existing vault

Bring a knowledge base you already have:

curl -X POST "https://api.hanzo.ai/v1/kb/import?format=obsidian" \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @vault.zip

{ "format": "obsidian", "imported": 214, "pages": ["index", "runbooks/deploy", "..."] }

format is obsidian (vault zip), notion (export zip), roam (JSON, raw or zipped), or evernote (.enex). Add &project= to file the import under a project.

Parents are created before children so the tree survives the trip, and colliding slugs get a numeric suffix — so re-importing adds rather than overwrites. imported counts what actually landed, not what was sent. Limits: 64 MB per upload, 5,000 pages, 8 MB per entry.

Connect a source

curl https://api.hanzo.ai/v1/kb/connectors/catalog \
  -H "Authorization: Bearer $HANZO_API_KEY"

The catalogue reports each provider's kind and whether this deployment has OAuth credentials for it. GitHub (repositories, READMEs, issues), Slack (channel history), and Google Drive (documents and files) are built in.

Connect with GET /v1/kb/connectors/{provider}/connect, pull with POST /v1/kb/connectors/{provider}/sync, list with GET /v1/kb/connectors, and remove with DELETE /v1/kb/connectors/{provider}. The OAuth state is signed over your verified org, so a callback can only ever land in your own tenant.

Connectors do not get a private write path — they produce ordinary documents that the same indexing hook picks up. Disconnecting removes that provider's vectors but keeps the documents; they simply stop being retrievable.

The graph

curl https://api.hanzo.ai/v1/kb/graph \
  -H "Authorization: Bearer $HANZO_API_KEY"

Nodes are ids of the form <doctype>:<name>. Edges come in exactly three kinds:

• parent — the page tree
• link — a wikilink. A link whose target does not exist yet becomes an unresolved node rather than vanishing, so the gap is visible
• provenance — an ingested source back to the connector that produced it

console.hanzo.ai → Knowledge draws this as a force-directed graph; clicking a node lists its neighbours by edge kind.

Related

• Memory — per-user memory in the AI API, a different store from kb-memory
• Vector — a managed vector database of your own
• Search — full-text and hybrid indexes
• Embeddings — the model behind this index
• API Reference — every endpoint at api.hanzo.ai