Import and export

By the end of this guide, you will know how to transfer collection records as JSON or CSV and which data needs a separate backup.

1. Export matching records

Use GET /api/v1/workspaces/:workspace/collections/:collection/records/export?format=json. CSV uses format=csv. Existing record query options apply; include_system=true includes IDs and timestamps.

Replace the workspace, collection and token placeholders. This example assumes the collection has a title field:

curl --get 'http://127.0.0.1:8080/api/v1/workspaces/YOUR_WORKSPACE/collections/YOUR_COLLECTION/records/export' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data-urlencode 'format=json' \
  --data-urlencode 'include_system=true' \
  --data-urlencode 'query={"fields":["title"],"sort":[{"field":"title","descending":false}]}'

Exports are bounded to 1,000 records and 1 MiB. They fail on overflow.

Note: Exports are paginated reads, not transactional backups. See Backup and upgrade for persistent storage.

2. Import new records atomically

Use POST /api/v1/workspaces/:workspace/collections/:collection/records/import. The JSON body has format (json or csv), a string content, and ignore_read_only:

{
	"format": "csv",
	"content": "title\nExample record\n",
	"ignore_read_only": false
}

For a collection with a writable title field and no other required input:

curl -X POST 'http://127.0.0.1:8080/api/v1/workspaces/YOUR_WORKSPACE/collections/YOUR_COLLECTION/records/import' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"format":"csv","content":"title\nExample record\n","ignore_read_only":false}'

An import atomically creates 1–100 validated records. Both the decoded file and the JSON request body are bounded to 1 MiB. New IDs and timestamps are generated. Reference IDs are retained without remapping.

Read-only metadata is rejected unless explicitly ignored with ignore_read_only: true. Unknown fields remain invalid even when read-only metadata is ignored.

3. Prepare CSV content

Use UTF-8, comma delimiters and standard CSV quoting.
Headers must be unique and match the collection schema.
Use true or false for booleans and JSON numeric syntax for numbers.
Encode JSON fields as JSON cells, with CSV quoting where needed.
Use \N for null. Empty text remains empty text.
Escape leading backslashes and formula-leading text by prefixing a backslash.

Note: The backslash escaping is a Kanesh convention. Prefer JSON for lossless transfer.

4. Account for excluded data

CSV/JSON transfers include file IDs, not binary uploads or relation links. Imports create records only: they do not upsert, write nested relations or create foreign keys/junctions. Retained reference IDs are not remapped to newly generated record IDs.

Troubleshooting

Export overflows: narrow the matching records or returned fields to stay within 1,000 records and 1 MiB.
Import is rejected: check the 1–100 record range, both 1 MiB limits, field names and required inputs.
An exported file cannot be imported with system fields: explicitly set ignore_read_only: true if you intend to discard that metadata and generate new values.
Files or relations are missing after transfer: binary files and relation links are outside the transfer contract.

Note: Transfer integration is verified on SQLite. PostgreSQL/MySQL runtime checks remain pending.

1. Export matching records

2. Import new records atomically

3. Prepare CSV content

4. Account for excluded data

Troubleshooting

Next steps