Import and export - KiwiFS — Markdown filesystem for agents and teams

Import

Bulk import data into your knowledge base. The import endpoint accepts the same source configuration options as the kiwifs import CLI command.

curl -X POST 'http://localhost:3333/api/kiwi/import' \
  -H "Content-Type: application/json" \
  -H "X-Actor: agent:importer" \
  -d '{
    "source": "postgres",
    "connection": "postgres://user:pass@localhost:5432/mydb",
    "query": "SELECT id, title, body FROM articles WHERE updated_at > '\''2026-01-01'\''",
    "mapping": {
      "path": "articles/{{id}}.md",
      "title": "{{title}}",
      "content": "{{body}}"
    }
  }'

{"imported": 42, "skipped": 0, "archived": 3, "errors": []}

integer

Pages created or updated.

integer

Rows unchanged since last import.

integer

Pages tombstoned with _archived_at during a full sync (when source rows disappear).

array

Per-row error messages.

Source types

Source	Config value	Description
PostgreSQL	`postgres`	Import from PostgreSQL queries
MySQL	`mysql`	Import from MySQL queries
MongoDB	`mongodb`	Import from MongoDB collections
SQLite	`sqlite`	Import from SQLite databases
CSV	`csv`	Import from CSV files
JSON	`json`	Import from JSON or JSONL files
Notion	`notion`	Import from Notion workspace
Airtable	`airtable`	Import from Airtable bases
Google Sheets	`gsheets`	Import from Google Sheets
Confluence	`confluence`	Import from Confluence spaces
Obsidian	`obsidian`	Import from Obsidian vaults
DynamoDB	`dynamodb`	Import from DynamoDB tables
Redis	`redis`	Import from Redis keys
Elasticsearch	`elasticsearch`	Import from Elasticsearch indices
Firestore	`firestore`	Import from Google Firestore
YAML	`yaml`	Import from YAML files
Excel	`excel`	Import from `.xlsx` spreadsheets
Markdown	`markdown`	Import from a folder of `.md` files

Mapping template syntax

Use double-brace templates to map source fields to KiwiFS file paths and frontmatter:

{
  "path": "concepts/{{slug}}.md",
  "title": "{{name}}",
  "content": "{{body}}",
  "frontmatter": {
    "source": "postgres",
    "source_id": "{{id}}",
    "status": "draft"
  }
}

Large imports can take time. The endpoint responds synchronously. For very large datasets, consider using the CLI kiwifs import command with progress output.

Upload file for import

Upload a file to the server for import processing.

POST /import/upload
Content-Type: multipart/form-data

The uploaded file is stored temporarily and can be referenced by subsequent POST /import calls.

List supported sources

GET /import/sources

Returns the list of supported import source types and their required configuration fields.

["postgres", "mysql", "sqlite", "mongodb", "firestore", "dynamodb", "redis", "elasticsearch", "csv", "json", "jsonl", "yaml", "excel", "notion", "airtable", "gsheets", "obsidian", "confluence", "markdown"]

Import browse

List tables or collections for a source before you run a full import. Same base URL prefix: http://localhost:3333/api/kiwi.

POST /import/browse
Content-Type: application/json

Body fields depend on from (same family as POST /import):

`from`	Required fields (typical)
`postgres`	`dsn`
`mysql`	`dsn`
`mongodb`	`uri` (or `dsn`), `database`
`firestore`	`project`, optional `credentials` JSON

{ "from": "postgres", "dsn": "postgres://user:pass@localhost:5432/db" }

{ "tables": [{ "name": "articles" }, { "name": "comments" }] }

Unsupported from values return 400 when browse is not implemented for that source.

Import preview

Fetch sample rows without writing pages. Uses the same JSON shape as POST /import, plus optional limit (default 5, max 20).

POST /import/preview
Content-Type: application/json

{
  "records": [
    {
      "path": "postgres/acme.md",
      "frontmatter": { "_source": "postgres", "_source_id": "...", "title": "Acme" },
      "body_preview": "# Acme\n\n> Auto-imported from postgres (row ...)"
    }
  ]
}

Import connections

When a connection store is enabled, the server persists metadata only (never secrets). Re-runs require credentials in the request body.

Method	Path	Purpose
`GET`	`/import/connections`	List saved connections (empty array if disabled).
`POST`	`/import/connections`	Save or update metadata (`from`, `name`, `dsn`, `uri`, `table`, `collection`, `database`, `database_id`, `base_id`, `table_id`, `project`, `prefix`, `id_column`, `columns`, last-run stats, etc.).
`DELETE`	`/import/connections/:id`	Remove a connection. `204`.
`POST`	`/import/connections/:id/run`	Run import again. Body may include `credentials` and/or `api_key` for that run only. Response matches `POST /import`: `{ "imported", "skipped", "archived", "errors" }`.
`POST`	`/import/connections/:id/sync`	Enable, pause, or change auto-sync interval. Body: `{ "enabled": true, "interval": "1h" }`.

Ingest from files

Convert supported office and document formats to markdown (MarkItDown pipeline).

POST /ingest
Content-Type: application/json

{
  "file": "/tmp/report.pdf",
  "split_mode": "single",
  "prefix": "imports/",
  "extract_keywords": true,
  "max_keywords": 10,
  "convert_crossrefs": false,
  "actor": "ingest-bot"
}

file must use an extension the server accepts for MarkItDown.
split_mode defaults to single.

Export

Export your knowledge base in structured formats.

string

required

Output format: jsonl, csv, or parquet.

string

Scope export to a subdirectory (e.g. concepts).

string

Comma-separated frontmatter fields to include as columns.

boolean

default:"false"

Include the full markdown body in the export.

boolean

default:"false"

Include outgoing wiki links for each page.

boolean

default:"false"

Include vector embeddings (if available).

integer

Maximum number of pages to export.

curl 'http://localhost:3333/api/kiwi/export?format=jsonl&path=concepts&include-content=true'

curl 'http://localhost:3333/api/kiwi/export?format=csv&columns=title,status,updated&path=concepts'

curl 'http://localhost:3333/api/kiwi/export?format=jsonl&include-content=true&include-links=true&include-embeddings=true'

JSONL output

Each line is a JSON object representing one page:

{"path":"concepts/auth.md","title":"Authentication","status":"verified","content":"# Authentication\n\nOAuth2 + JWT...","links":["users","billing"]}
{"path":"concepts/billing.md","title":"Billing","status":"draft","content":"# Billing\n\nStripe integration...","links":["users"]}

CSV output

path,title,status,updated
concepts/auth.md,Authentication,verified,2026-04-25
concepts/billing.md,Billing,draft,2026-04-20

Use JSONL export with include-content=true to create backups or to feed your knowledge base into external pipelines.

Document export

Render markdown to PDF, HTML, slides, or a static site:

POST /export/document
Content-Type: application/json

See Document export for the full request body and examples.

Airbyte endpoints

Method	Path
`POST`	`/import/airbyte/spec`
`POST`	`/import/airbyte/check`
`POST`	`/import/airbyte/discover`
`POST`	`/import/airbyte-cloud/check`
`POST`	`/import/airbyte-cloud/discover`
`GET`	`/import/airbyte-cloud/connections`
`POST`	`/import/airbyte-cloud/sync`
`GET`	`/import/sync/status`

See Airbyte import.

​Import

​Upload file for import

​List supported sources

​Import browse

​Import preview

​Import connections

​Ingest from files

​Export

​JSONL output

​CSV output

​Document export

​Airbyte endpoints

Import

Upload file for import

List supported sources

Import browse

Import preview

Import connections

Ingest from files

Export

JSONL output

CSV output

Document export

Airbyte endpoints