Skip to main content

​
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": []}
​
imported
integer
Pages created or updated.
​
skipped
integer
Rows unchanged since last import.
​
archived
integer
Pages tombstoned with _archived_at during a full sync (when source rows disappear).
​
errors
array
Per-row error messages.
SourceConfig valueDescription
PostgreSQLpostgresImport from PostgreSQL queries
MySQLmysqlImport from MySQL queries
MongoDBmongodbImport from MongoDB collections
SQLitesqliteImport from SQLite databases
CSVcsvImport from CSV files
JSONjsonImport from JSON or JSONL files
NotionnotionImport from Notion workspace
AirtableairtableImport from Airtable bases
Google SheetsgsheetsImport from Google Sheets
ConfluenceconfluenceImport from Confluence spaces
ObsidianobsidianImport from Obsidian vaults
DynamoDBdynamodbImport from DynamoDB tables
RedisredisImport from Redis keys
ElasticsearchelasticsearchImport from Elasticsearch indices
FirestorefirestoreImport from Google Firestore
YAMLyamlImport from YAML files
ExcelexcelImport from .xlsx spreadsheets
MarkdownmarkdownImport from a folder of .md files
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):
fromRequired fields (typical)
postgresdsn
mysqldsn
mongodburi (or dsn), database
firestoreproject, 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.
MethodPathPurpose
GET/import/connectionsList saved connections (empty array if disabled).
POST/import/connectionsSave 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/:idRemove a connection. 204.
POST/import/connections/:id/runRun 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/syncEnable, 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.
​
format
string
required
Output format: jsonl, csv, or parquet.
​
path
string
Scope export to a subdirectory (e.g. concepts).
​
columns
string
Comma-separated frontmatter fields to include as columns.
​
include-content
boolean
default:"false"
Include the full markdown body in the export.
​
include-links
boolean
default:"false"
Include outgoing wiki links for each page.
​
include-embeddings
boolean
default:"false"
Include vector embeddings (if available).
​
limit
integer
Maximum number of pages to export.
curl 'http://localhost:3333/api/kiwi/export?format=jsonl&path=concepts&include-content=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

MethodPath
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.
Last modified on May 31, 2026