Browse, preview, and sync imports

Beyond a one-shot POST /api/kiwi/import, the REST API lets tools and agents explore a source first, preview the exact pages an import would write, and keep a source in sync. The web UI import wizard in the Data sources panel is built on these endpoints. A typical flow:

Browse

List the tables or collections in the source.

Infer fields

Sample records and get suggested field names and types.

Preview

See the paths and frontmatter for a few records without writing anything.

Import

Run POST /api/kiwi/import. Live sources are saved as connections and auto-synced.

Browse tables and collections

POST /api/kiwi/import/browse lists the tables or collections in a postgres, mysql, mongodb, or firestore source.

Terminal

curl -X POST http://localhost:3333/api/kiwi/import/browse \
  -H "Content-Type: application/json" \
  -d '{"from": "postgres", "dsn": "postgres://user:pass@db:5432/mydb"}'

Response

{ "tables": [{ "name": "users", "estimated_count": 1200 }, { "name": "orders" }] }

Source	Required fields
`postgres`, `mysql`	`dsn`
`mongodb`	`uri`, `database`
`firestore`	`project`, plus optional `credentials` (service account JSON)

Preview pages

POST /api/kiwi/import/preview reads a few records and returns the path, frontmatter, and the start of the body for each one, without writing pages. It takes the same body as POST /api/kiwi/import, including path for markdown and obsidian and query for SQL sources.

Terminal

curl -X POST http://localhost:3333/api/kiwi/import/preview \
  -H "Content-Type: application/json" \
  -d '{"from": "obsidian", "path": "/srv/vaults/research", "limit": 3}'

Response

{
  "records": [
    {
      "path": "research/ideas/graph-search.md",
      "frontmatter": { "tags": ["search"], "_source": "research" },
      "body_preview": "# Graph search\n\nNotes on ..."
    }
  ]
}

limit defaults to 5 and is capped at 20.

Infer fields

POST /api/kiwi/import/infer-fields samples up to 100 records and suggests a type for each field. It takes the same body as preview.

Response

{
  "fields": [
    { "source": "email", "target": "email", "type": "string" },
    { "source": "signup_date", "target": "signup_date", "type": "date" }
  ]
}

Send the edited list back as field_mappings on preview or import to rename, retype, or skip fields. Each mapping has source, target, type (string, number, boolean, or date), and skip. When you send any mappings, fields you leave out are dropped.

Saved connections

KiwiFS saves connection metadata in .kiwi/state/imports.json so you can re-run an import or keep it in sync. A successful POST /api/kiwi/import saves or updates a connection automatically, matched by source and prefix.

Method	Path	Purpose
`GET`	`/api/kiwi/import/connections`	List saved connections
`POST`	`/api/kiwi/import/connections`	Save or update a connection
`DELETE`	`/api/kiwi/import/connections/:id`	Remove a connection
`POST`	`/api/kiwi/import/connections/:id/run`	Run the import again
`POST`	`/api/kiwi/import/connections/:id/sync`	Turn auto-sync on or off, or change its interval
`GET`	`/api/kiwi/import/sync/status`	List connections with auto-sync on

Re-running a connection takes the secrets again in the body, because KiwiFS never stores the credentials or api_key fields:

Terminal

curl -X POST http://localhost:3333/api/kiwi/import/connections/CONNECTION_ID/run \
  -H "Content-Type: application/json" \
  -d '{"api_key": "ntn_..."}'

The dsn and uri fields are saved as you send them. If a connection string contains a password, that password is written to .kiwi/state/imports.json. Keep that directory out of version control, as it is by default.

Auto-sync

Live sources can re-import on a schedule: postgres, mysql, mongodb, firestore, notion, airtable, and the Airbyte source firebase-rtdb. When you import one of these sources over REST, KiwiFS saves the connection with auto-sync on and an interval of 1h. A background scheduler checks for due connections every 30 seconds.

Terminal

curl -X POST http://localhost:3333/api/kiwi/import/connections/CONNECTION_ID/sync \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "interval": "6h"}'

interval is a Go duration such as 5m, 1h, or 24h. Send {"enabled": false} to pause. Each connection reports a sync_status of idle, running, or error, with details in sync_error. Scheduled runs don’t receive request secrets. They work when the connection string carries its own credentials, or when the server has them from its environment, such as NOTION_API_KEY, AIRTABLE_API_KEY, or Google Application Default Credentials.

Archived records

Scheduled syncs and REST imports of live sources without a limit run as a full sync. Pages from the same source that no longer appear in the latest run get an _archived_at timestamp in their frontmatter instead of being deleted. If the record comes back, the next import rewrites the page without the marker.

Response

{ "imported": 12, "skipped": 40, "archived": 3, "errors": [] }

CLI and MCP imports never archive pages.

Ingest documents

POST /api/kiwi/ingest converts a PDF, Word, PowerPoint, Excel, HTML, EPUB, or image file into markdown pages with MarkItDown. Use it for documents. Use import for structured records.

Terminal

curl -X POST http://localhost:3333/api/kiwi/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "file": "/srv/inbox/annual-report.pdf",
    "split_mode": "sections",
    "prefix": "reports/annual-2026",
    "extract_keywords": true
  }'

Field	Default	Description
`file`		Path on the server (required)
`split_mode`	`single`	`single` writes one page. `sections` writes one page per top-level heading.
`prefix`	From file name	Output folder
`extract_keywords`	`false`	Add TF-IDF keywords to frontmatter
`max_keywords`	`10`	Keywords per section
`convert_crossrefs`	`false`	Turn “See Section 2.1” references into wiki links
`actor`		Name recorded in the commit

Response

{
  "source_file": "/srv/inbox/annual-report.pdf",
  "format": "pdf",
  "total_sections": 6,
  "output_files": ["reports/annual-2026/overview.md", "..."],
  "top_keywords": ["revenue", "growth"]
}

Agents can call the same pipeline with the kiwi_ingest MCP tool.

Ingest runs the markitdown command, which isn’t in the KiwiFS Docker image. Install it on the server with pip install 'markitdown[all]'.

Import API

Full request and response reference.

Web UI

The Data sources panel and import wizard.

Getting Started

Core Concepts

Widgets

Guides

Data Import

Data Export

Deployment

Browse tables and collections

Preview pages

Infer fields

Saved connections

Auto-sync

Archived records

Ingest documents

Import API

Web UI

​Browse tables and collections

​Preview pages

​Infer fields

​Saved connections

​Auto-sync

​Archived records

​Ingest documents

​Related

Import API

Web UI

Browse tables and collections

Preview pages

Infer fields

Saved connections

Auto-sync

Archived records

Ingest documents

Related