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.
| Field | Type | Description |
|---|---|---|
docid | string, required | Library file ID of the CSV, not a URL or path. |
columnMapping | array, optional | Ordered 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.
| Field | Description |
|---|---|
source | Exact original header, including spaces and case. |
target | Destination column name following the identifier rules. Required for imported columns. |
type | text, numeric, boolean, date, timestamp, or uuid. Required for imported columns. |
import | Set 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.