Import & Export

Import data from files and export datasets to various formats.

POST /api/datasets/{id}/_import

Import data from an uploaded file.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Dataset ID or slug

Request Body:

Field	Type	Required	Description
upload	string	Yes	Upload ID from file upload
uploadOptions	object	No	Parsing options
progress	number	No	Progress tracking ID

Upload Options:

Option	Type	Default	Description
hasHeaders	boolean	true	First row contains headers
delimiter	string	,	CSV delimiter character
encoding	string	utf-8	File encoding
dateFormat	string	YYYY-MM-DD	Date parsing format
numberFormat	string	en-US	Number locale format

Example Request:

{
  "upload": "upload-abc123",
  "uploadOptions": {
    "hasHeaders": true,
    "delimiter": ",",
    "encoding": "utf-8"
  },
  "progress": 12345
}

Response:

{
  "imported": 5000,
  "records": 5000,
  "duration": 3421,
  "fieldsAdded": 3,
  "success": true
}

---

GET /api/datasets/{id}/export/{exporter}

Export dataset data to a specific format.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Dataset ID or slug
exporter	string	Exporter ID (csv, excel, pdf, etc.)

Query Parameters:

Parameter	Type	Description
omit	array	Fields to exclude
include	array	Fields to include (overrides omit)
sort	string	Sort field
q	string	Search query
filter	string	Filter ID or criteria
settings	object	Exporter-specific settings
options	object	Export options
timezone	string	Timezone for dates
locale	string	Locale for formatting
applyFormatting	boolean	Apply field formatting
snapshots	object	Snapshot configuration

Timeout: 60 minutes (3600000ms)

Example:

GET /api/datasets/sales-2024/export/csv?sort=-amount&limit=1000&applyFormatting=true

Response:

Direct file download with appropriate Content-Type and Content-Disposition headers.

---

POST /api/datasets/{id}/export/{exporter}

Export dataset and create a downloadable file.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Dataset ID or slug
exporter	string	Exporter ID

Request Body:

Field	Type	Description
progress	number	Progress tracking ID
filename	string	Output filename
label	string	Download label
options	object	Export options
settings	object	Exporter settings
snapshots	object	Snapshot configuration
applyFormatting	boolean	Apply field formatting
filter	string	Filter ID or criteria

Example Request:

{
  "filename": "sales-report-2024.xlsx",
  "label": "Q1 Sales Report",
  "options": {
    "includeHeaders": true,
    "sheetName": "Sales Data"
  },
  "applyFormatting": true,
  "progress": 67890
}

Response:

{
  "downloadId": "download-xyz789",
  "filename": "sales-report-2024.xlsx",
  "size": 2048576,
  "exporter": "excel",
  "createdAt": "2024-02-08T16:00:00Z",
  "_links": {
    "download": { "href": "/api/downloads/download-xyz789" }
  }
}

Timeout: 60 minutes (3600000ms)

---

GET /api/datasets/{id}/exporters

Get available exporters for a specific dataset.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Dataset ID or slug

Response:

{
  "exporters": [
    {
      "id": "csv",
      "name": "CSV",
      "mimeType": "text/csv",
      "extension": "csv",
      "supportsFormatting": true,
      "supportsSnapshots": true
    },
    {
      "id": "excel",
      "name": "Excel",
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "extension": "xlsx",
      "supportsFormatting": true,
      "supportsSnapshots": true
    },
    {
      "id": "pdf",
      "name": "PDF",
      "mimeType": "application/pdf",
      "extension": "pdf",
      "supportsFormatting": true,
      "supportsSnapshots": false
    }
  ]
}

---

GET /api/datasets/exporters

Get all dataset exporters available globally.

Authentication: Required

Query Parameters:

Parameter	Type	Description
onlyEmbedded	boolean	Return only embedded exporters
unfiltered	boolean	Superuser: return all exporters

Response:

{
  "exporters": [
    {
      "id": "csv",
      "name": "CSV",
      "description": "Comma-separated values",
      "mimeType": "text/csv",
      "extension": "csv",
      "embedded": false,
      "settings": {
        "delimiter": ",",
        "includeHeaders": true,
        "quoteAll": false
      }
    },
    {
      "id": "excel",
      "name": "Excel",
      "description": "Microsoft Excel spreadsheet",
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "extension": "xlsx",
      "embedded": false,
      "settings": {
        "sheetName": "Data",
        "includeHeaders": true,
        "autoFilter": true
      }
    }
  ]
}

---

GET /api/dataset-upload-form

Get upload form options/schema for a file.

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
upload	string	Yes	Upload ID

Response:

{
  "upload": "upload-abc123",
  "filename": "sales-data.csv",
  "size": 1048576,
  "mimeType": "text/csv",
  "detected": {
    "hasHeaders": true,
    "delimiter": ",",
    "encoding": "utf-8",
    "rowCount": 5000,
    "columnCount": 8,
    "sample": [
      ["order_id", "customer", "amount", "date"],
      ["ORD-001", "Acme Corp", "1500.00", "2024-01-15"],
      ["ORD-002", "TechStart", "2300.00", "2024-01-16"]
    ]
  },
  "options": {
    "hasHeaders": {
      "type": "boolean",
      "default": true,
      "label": "First row contains headers"
    },
    "delimiter": {
      "type": "string",
      "default": ",",
      "label": "Delimiter",
      "options": [",", ";", "\t", "|"]
    },
    "encoding": {
      "type": "string",
      "default": "utf-8",
      "label": "Encoding",
      "options": ["utf-8", "iso-8859-1", "windows-1252"]
    }
  }
}

---

Exporter Types

CSV Exporter

{
  "id": "csv",
  "settings": {
    "delimiter": ",",
    "includeHeaders": true,
    "quoteAll": false,
    "encoding": "utf-8"
  }
}

Excel Exporter

{
  "id": "excel",
  "settings": {
    "sheetName": "Data",
    "includeHeaders": true,
    "autoFilter": true,
    "freezeHeaders": true,
    "columnWidths": "auto"
  }
}

PDF Exporter

{
  "id": "pdf",
  "settings": {
    "orientation": "landscape",
    "pageSize": "letter",
    "fontSize": 10,
    "includeHeaders": true,
    "fitToPage": true
  }
}

JSON Exporter

{
  "id": "json",
  "settings": {
    "pretty": true,
    "includeMetadata": false
  }
}

HTML Exporter

{
  "id": "html",
  "settings": {
    "includeStyles": true,
    "responsive": true,
    "theme": "default"
  }
}

---

Best Practices

Import

• Validate uploads - Check file format before import
• Preview data - Show sample to user before committing
• Handle errors - Gracefully handle parsing failures
• Progress tracking - Show progress for large imports
• Backup first - Snapshot before major data imports

Export

• Limit size - Apply filters to reduce export size
• Format appropriately - Use applyFormatting for user-facing exports
• Include snapshots - For historical comparison exports
• Optimize settings - Tailor exporter settings to use case
• Timeout awareness - Warn users about large export timeouts

Performance

• Stream exports - Don't load all data in memory
• Batch processing - Process imports in chunks
• Background jobs - Queue large import/export operations
• Monitor progress - Track and report operation status
• Cache templates - Reuse export configurations