Kb

Package knowledge is your team's wiki and your agents' memory, searchable by meaning.

kb

GET /v1/kb/connectors/{provider}/callback

CompleteConnectorOAuth finishes an OAuth connection: it exchanges the provider's code for a token, seals that token in KMS, and records the connection. THE ORG COMES FROM THE SIGNED STATE, not from a header and not from the provider, so an attacker cannot bind their own account to someone else's org — a tampered, expired or foreign-provider state is refused outright. The token itself is never returned, never written into the document, and never logged; the document holds only its KMS path.

GET /v1/kb/connectors/{provider}/connect

StartConnectorOAuth returns the provider authorize URL the console opens to connect this org's account. There is no server-side redirect — the console stays in control of the navigation. The URL carries a state this server SIGNED over the caller's validated org, so the connection the callback completes can only ever land in that org.

POST /v1/kb/connectors/{provider}/sync

Pulls the provider's documents for the caller's org and files them as knowledge sources, which the store's own hook then indexes — so a synced document is retrievable exactly like a hand-written page. The org is the validated tenant and the credential is read from KMS, so an org can only ever sync its own connection. A provider failure is reported honestly (502) and recorded on the connector rather than silently swallowed.

DELETE /v1/kb/connectors/{provider}

Revokes a connection: it tombstones the stored credential so a later sync cannot reuse it, purges this provider's points from the org's vector namespace, and marks the connector disconnected. The documents already ingested stay in the org's store — they are the org's own data — but stop being retrievable by search; a caller deletes them through the document surface.

GET /v1/kb/connectors/catalog

Returns the ONE catalog of everything a caller can connect: every first-party connector and every long-tail one, in a single list sorted by provider. configured reports whether this deployment holds OAuth credentials for a source, so the console can show Connect rather than a dead button, and kind is a badge only — the connect and sync lifecycle is identical for both. The catalog itself is org-independent; a validated principal is still required. It is metadata only: no secret is ever returned.

GET /v1/kb/connectors

Returns every supported knowledge connector with THIS org's connection state and the REAL number of documents each has ingested into the org's store. A provider that is configured for the deployment but not yet connected appears as disconnected, so the console can offer a Connect button. No secret is ever returned.

GET /v1/kb/graph

Returns the caller org's knowledge as a node/edge graph shaped for a force-directed renderer: pages, memories and synced sources as nodes; the page parent tree, the wikilinks between pages, and each source's connector provenance as edges. Wikilink targets are resolved HERE by title or slug, so a rename never needs an edge rewrite and a link that matches no page renders as its own "unresolved" node instead of vanishing. ?project= narrows it. A store outage degrades to an honest empty graph, never a 5xx.

POST /v1/kb/import

Import an Obsidian, Notion, Roam or Evernote export into the org's knowledge base

Ingests an uploaded export as a tree of kb-page documents with its link structure intact. ?format= picks the normalizer — obsidian, notion, roam or evernote — and the export arrives as a multipart file part, or as the raw request body when there is no multipart part: an Obsidian or Notion vault zip, a Roam JSON (raw or inside the zip Roam downloads), or an Evernote .enex.

The pages are filed through the SAME ingest path a connector sync uses, so the kb-page hook indexes each one for retrieval AND extracts its [[wikilinks]] into kb-link edges — the imported vault is searchable and its graph is navigable without a second pass. Parents are filed before their children, and each page takes a slug unique within the org (suffixed -2, -3, … on collision), so a re-import adds pages rather than overwriting the ones already there.

Scoped to the caller's validated org; ?project= narrows every imported page to one project. No validated principal is 403, and an org that has not installed the kb module is refused with the install call to make first. The bounds are 64 MB per upload, 5000 pages and 8 MB per archive entry: pages past the five-thousandth are dropped and a larger entry is truncated at its bound, and a page the store rejects is skipped — so the answer's imported count is what was actually filed, not what was sent.

POST /v1/kb/search

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 body — application/json (required)

---

All Hanzo APIs · Interactive reference