# Import knowledge

URL: https://docs.hanzo.ai/docs/openapi/knowledge/post-knowledge-import

> Ingests an uploaded export as a tree of kb.page documents with its link structure intact.

`POST /v1/knowledge/import`

> [Knowledge →](https://docs.hanzo.ai/docs/openapi/knowledge) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                            |
| ------------- | ------------------------------------------ |
| **Address**   | `https://api.hanzo.ai/v1/knowledge/import` |
| **Method**    | `POST`                                     |
| **Operation** | `post_knowledge_import`                    |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY`     |

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.

## Request

The document declares no body for `POST /v1/knowledge/import`. The handler is typed in cloud but its shape is not yet emitted, so the fields are not listed here — ask MCP's `describe` for `post_knowledge_import`, which answers from the running route.

## Response

The document declares no response body for this operation. It answers `200` on success and the platform error shape on failure — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo knowledge import
```

**SDK**

**.ts**

```ts
import { Configuration, KnowledgeApi } from 'hanzoai';

const api = new KnowledgeApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postKnowledgeImport();
```

**.py**

```python
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_import()
```

**.go**

```go
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.KnowledgeAPI.PostKnowledgeImport(context.Background()).Execute()
if err != nil {
	return err
}
```

**.rs**

```rust
use hanzo_client::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_import(&cfg, Default::default()).await?;
```

**.java**

```java
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.KnowledgeApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new KnowledgeApi(client).postKnowledgeImport();
```

**HTTP**

```bash
curl -X POST https://api.hanzo.ai/v1/knowledge/import \
  -H "Authorization: Bearer $HANZO_API_KEY"
```

**MCP**

MCP reaches **knowledge** through the `knowledge` tool, which names its 9 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them:

```bash
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_knowledge_connectors"
         }
       }
     }'
```

---

[Knowledge API](https://docs.hanzo.ai/docs/openapi/knowledge) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)