Export and import

Export a knowledge base as a .simkb.zip archive. It carries the base's configuration, tag definitions and values, stored document files, and completed chunk text, with vectors included by default. Import the archive into any workspace, on this deployment or another, to create a new knowledge base from it.

Access and scope

Export requires at least workspace read access and the Knowledge Base Export capability. Enterprise permission groups can restrict members' exports. The API accepts supported personal credentials or a workspace API key; OAuth callers need api:read. A workspace API key uses its workspace role and operation policy rather than a member's permission group. See API authentication.

The archive includes active, included documents readable by the workspace as a whole. It does not include every document a particular member can personally access through source permissions. Archived, deleted, and excluded documents are left out.

Documents with neither a stored file nor completed chunks are omitted. A document still processing can contribute its stored file, but not unfinished chunk text. Disabled flags are preserved for documents and chunks that are included.

Download the archive

Right-click a base in the knowledge base list and choose Export, or open the base and choose Export in its header. The download is named <base name>.simkb.zip.

API

GET /api/v2/knowledge/{knowledgeBaseId}/export?workspaceId={workspaceId}&vectors=true

The response is the ZIP archive. Set vectors=false to leave out embeddings. See Export knowledge base for the request contract.

CLI

sim knowledge export <knowledgeBaseId> --output-file kb.zip
sim knowledge export <knowledgeBaseId> --output-file kb.zip --no-vectors

The CLI uses the selected workspace profile. An existing output file requires --force to overwrite it. See the CLI reference.

Import an archive

Importing creates a new knowledge base from a .simkb.zip archive. It never changes an existing base.

Access

Import requires workspace write access and both the Knowledge Base Creation and Knowledge Base Uploads capabilities. OAuth callers need api:write; a workspace API key is accepted.

CLI

sim knowledge import ./kb.simkb.zip
sim knowledge import ./kb.simkb.zip --name "Product Documentation (copy)"
sim knowledge import ./kb.simkb.zip --no-wait

The new base takes the archive's name unless you pass --name. Knowledge base names are unique within a workspace, so importing next to the original needs a new name. The command uploads the archive, waits for the import to finish, and prints the new base's id with how many documents were imported. With --no-wait it returns as soon as the import starts.

To check on or stop an import that is still running:

sim knowledge imports get <importId>
sim knowledge imports cancel <importId>

API

An import is three requests, like other large uploads:

1. POST /api/v2/knowledge/imports with the workspace, an optional name, and the archive's file name, type, and size. The response carries the import id, an upload token, and signed transfer instructions.
2. Upload the archive's bytes as instructed. Multipart transfers request part URLs from POST /api/v2/knowledge/imports/{importId}/parts.
3. POST /api/v2/knowledge/imports/{importId}/complete to start the import.

Poll GET /api/v2/knowledge/imports/{importId}?workspaceId={workspaceId} until status is completed, failed, or canceled. See Create knowledge base import for the request contracts.

What the import creates

The new base is created at the workspace root with the archive's description, chunking configuration, and tag definitions. Each document keeps its filename, tag values, and enabled flag, and its original file when the archive has one. It is attributed to the person who imported it.

How a document is indexed depends on the embedding model:

• Same model: when the archive includes vectors from the embedding model and dimensions this deployment uses, documents are indexed directly from the archive's chunks and vectors. Nothing is re-embedded, so nothing is billed for embeddings, and chunk enabled flags are kept.
• Different model or no vectors: documents are processed from their original files, exactly as uploads are, and appear in the base as their processing finishes. A document with chunks but no original file is re-embedded from its chunk text instead.

A document the archive carries only as chunks, such as one from a connector, is stored as a plain-text file holding its chunk text, so it can still be reprocessed later.

documentsImported counts documents created; re-indexed documents may still be processing when the import completes. Documents that cannot be imported, such as an unsupported file type or a storage limit reached partway through, are skipped and reported in failures; the rest of the import continues.

Limits

Archives must be .zip files of at most 5 GiB, and every document file at most 100 MB. The archive is validated before anything is created, so a damaged or modified archive fails without leaving a partial base. Imports count toward storage and usage limits like uploads do.

Canceling stops after the document in progress. Documents already imported stay in the new base. Starting an import records one audit event, naming the knowledge base it creates.

Archive contents

<base name>.simkb.zip
├── manifest.json
├── files/
│   └── <documentId>/<filename>
└── chunks/
    └── <documentId>.ndjson

Files and chunk entries are present when the document has that content.

Each document entry records its filename, MIME type, file size, enabled flag, tag values, entry paths, and chunk, token, and character counts. Connector documents export as plain documents with their text and any stored file.

Vectors and portability

Vectors are the embeddings used to compare chunks with a query. Each exported vector is encoded as base64 float32 values in its chunk's NDJSON line.

The manifest records the base's embedding model and dimensions. Reusing its vectors requires both to match the destination configuration; equal dimensions alone do not make vectors from different models comparable. Use vectors=false or --no-vectors when you need a text-and-file archive without vectors.

What stays behind

The archive does not include:

• Access-control lists or source-permission grants.
• Connector links and credentials.
• Uploader identities.
• Internal storage keys or secret-provenance sidecars.

Live Organization Search queries providers directly and has no document index to export. A legacy indexed organization Search backend is also outside a workspace knowledge-base export.

Limits and audit

Export preflight accepts at most 2,000 active, included, workspace-readable document rows. A larger eligible set returns 413, even if some empty documents would otherwise be omitted from the archive.

The bundle format also bounds each document to 5,000 chunks and each chunk's content to 100,000 characters. These are format limits, independent of vector inclusion.

Each authorized export records an audit event with the base, vector option, and document count.

Related docs

• Knowledge Base — uploads, processing, and embedding compatibility.
• Connectors — source content and access methods.
• Access control — permission-group restrictions.