Skip to main content

Import a CSV

Queue an import from a Library CSV file into an existing database table.

POST /projects/:projectid/databases/:dbid/tables/:tblid/import-csv

Authentication​

Send the project API key in the Authorization header, without a Bearer prefix. Requires both databases.write for the destination database and library.read for the project Library.

Request​

First upload and complete the CSV file, create the destination table if needed, then read the CSV header.

FieldTypeDescription
docidstring, requiredLibrary file ID of the CSV, not a URL or path.
columnMappingarray, optionalOrdered mappings described below. Omit or use null to use valid CSV headers directly.

The file must have a header row, be non-empty, and be no larger than 5 GiB. The destination table must already exist. Missing destination columns are added; existing column types are not changed.

Example​

Use the environment variables from the database overview. Replace example IDs with your own.

curl --include --request POST \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"docid": "csv_document_id",
"columnMapping": [
{
"source": "Customer Name",
"target": "customer_name",
"type": "text"
},
{
"source": "Email",
"target": "email",
"type": "text"
},
{
"source": "Signup Date",
"target": "signup_date",
"type": "date"
}
]
}' \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/databases/${INTELLECTIBLE_DATABASE_ID}/tables/${INTELLECTIBLE_TABLE_ID}/import-csv"

Response​

202 Accepted

{
"importId": "import_id",
"status": "queued"
}

Save importId and use Get CSV import status until the import reports complete or failed. An accepted request does not mean the rows are ready.

Column mapping​

Provide exactly one mapping entry per CSV column, in the same order as the header.

FieldDescription
sourceExact original header, including spaces and case.
targetDestination column name following the identifier rules. Required for imported columns.
typetext, numeric, boolean, date, timestamp, or uuid. Required for imported columns.
importSet to false to skip this CSV column; otherwise it is imported.

Skipped columns still need an entry with the matching source. At least one column must be imported, and imported target names must be unique. CSV mapping uses numeric, whereas the separate Create a column endpoint uses number.

Without a mapping, headers must already be unique valid column names, and new columns are created as text. With a mapping, values must be compatible with the selected types and any existing destination columns.

Failures and retries​

Imports append rows; they are not an upsert or table-replacement operation. Existing constraints still apply.

Imports commit in batches. If a later batch fails, earlier committed rows remain in the table. Check rowsCommitted and inspect the destination before retrying. Repeating the request queues a new import and can duplicate data. For imports that need to be published all at once, import into a separate staging table, verify the result, and only then make the data available to your application.

See Errors and safe retries for shared failure handling.