Workspace export and import

Export a workspace's resources and connections as a portable archive, then import that archive into another workspace, on the same installation or a different one. Import always shows you a plan first, never deletes anything, and keeps imported resources separate from the ones Kumo.io syncs from your cloud.

Applies to: BothPlan: Teamplan before you applynever deletesCLI and API only

Two kinds of workspace export Export a workspace archive Import an archive Who can export and import

Two kinds of workspace export

Kumo.io has two ways to get a workspace's data out, for two different jobs:

	Data export	Workspace archive
For	Spreadsheets, scripts, a data warehouse	Moving a workspace's graph into another workspace
Formats	CSV, JSON, or a ZIP of both	NDJSON or ZIP archive
Where	Export Data on the workspace's Overview tab, or the API	The CLI or the API
Can be imported	No	Yes

This page covers the workspace archive. For data exports, see How do I get a diagram or data out of Kumo.io?

There's no import or archive button in the app; use the CLI or the API.

Export a workspace archive

From the CLI (self-hosted)

On a self-hosted installation, run on the installation:

kumo workspace export --workspace <id-or-name> --out export.ndjson
kumo workspace export --workspace <id-or-name> --out export.zip --format zip
kumo workspace export --workspace <id-or-name> --out resources.ndjson --kinds resource

--format is ndjson (the default) or zip.
--kinds chooses what to include: resource, connection, or both (the default, resource,connection).
The export reads the workspace's latest revision.

The command prints the number of objects written, the export id and the archive's SHA-256 content hash.

Through the API

GET /v1/accounts/{accountId}/workspaces/{workspaceId}/export/archive?format=ndjson&kinds=resource,connection

The response is the archive as a download. The X-Kumo-Export-Object-Count and X-Kumo-Export-Content-Hash headers carry the object count and content hash.

Import an archive

Importing is always two steps: plan it, then apply it.

1. Plan the import

kumo workspace import plan --file ./prod-export.ndjson --workspace staging

The plan checks the archive and lists what an apply would do: how many objects it would create, update, skip or reject. It changes nothing. If the archive is invalid or damaged, the plan says so, lists the problems, and exits with status 2.

2. Apply it

kumo workspace import apply --file ./prod-export.ndjson --workspace staging --idempotency-key prod-2026-08-15

Apply re-plans and then writes the archive's objects into the target workspace as a new revision. It reports how many objects were created, updated, skipped, rejected or failed, and exits with status 2 if the import failed. Running it again with the same --idempotency-key doesn't import twice. Without a key, the CLI generates a new one each time.

Both commands detect NDJSON or ZIP automatically, take --format json for machine-readable output, and run against the installation's own database, so they aren't available against kumo.io. There, use the API.

What happens to existing objects

Use --conflict-mode to choose what happens when an object from the archive is already in the target workspace, for example because you imported the same archive before:

Mode	An object that's already there is
`create_only` (default)	Rejected, and recorded as a conflict.
`skip_existing`	Skipped.
`upsert_safe`, `merge`, `replace`	Updated in place.
`restore`	Updated in place, the same as `replace`.

Whatever the mode, an import never deletes anything. Objects in the target workspace that aren't in the archive are left as they are.

Imported resources stay separate

Imported resources and connections get new ids in the target workspace, and they never merge with resources Kumo.io syncs from your cloud. Importing an archive of production into a staging workspace adds production's resources alongside staging's own; it doesn't overwrite them.

Import through the API

Request	What it does
`POST …/import/inspect`	Plans the import and returns the plan.
`POST …/import/apply`	Applies the import and returns the result. Requires `idempotencyKey`.
`POST …/import/jobs`	Applies the import in the background and returns a job (status `202`) to track. Also requires `idempotencyKey`.

Paths are relative to /v1/accounts/{accountId}/workspaces/{workspaceId}. Send the archive base64-encoded in the archive field of a JSON body, with an optional conflictMode. Requests can be up to 32 MiB, including the base64 encoding (which adds about a third to the archive's size); a damaged archive is refused with a 400. See How do I track a long-running request? and How do I authenticate to the API?

Who can export and import

Exporting an archive needs a plan with exports: Team and above on kumo.io, or Enterprise (Licensed) on a self-hosted installation. It isn't part of a trial. It still works while an account is read-only after a paid plan ends.
Planning an import needs a role that can read the target workspace. Applying one needs a role that can manage it.