Skip to main content
POST
Create the table and start loading its rows

Authorizations

X-API-Key
string
header
required

Path Parameters

import_id
string<uuid>
required

Body

application/json

Request body for committing an upload.

Send the mapping the user reviewed. Omitting a field's entry leaves that column out of the table entirely, which is how a user drops a column they do not want.

columns
ImportColumnMappingSchema · object[]
required

The reviewed mapping, in display order.

Required array length: 1 - 500 elements
table_name
string
required

Name for the table this creates.

Required string length: 1 - 255
folder_id
string<uuid> | null

The folder to make the table in, as when the file is imported from inside one on the Tables list. Leave it out for the top level.

max_rows
integer | null

How many of the file's data rows to write, counted from the top: 1 or more. Clamped by the plan's own ceiling, so this can only ever import less than the preview's importable_row_count, never more. Omit it, or send null, for every row the plan allows; that is also how a file with a header and no data rows is committed. Named for the user's choice, unlike the preview's row_limit, which is the plan's cap.

Required range: x >= 1
row_ranges
ImportRowRangeSchema · object[] | null

Which of the file's data rows to write, the way a print dialog picks pages: rows 1 to 10 and 21 to 30 are two ranges. Rows are numbered as row_errors numbers them, from 1 under the header, blank lines not counted. Overlapping and touching ranges are merged, an end past the file's last row is brought back to it, and a choice bigger than the plan's row_limit keeps its first rows up to it. Rows past the preview's importable_row_count may be chosen: the plan caps how many rows a table holds, not which. A choice wholly past the end of the file is refused, and so is one of more than 100 ranges once merged. Send this or max_rows, never both; omit both for every row the plan allows.

Required array length: 1 - 1000 elements

Response

Successful Response

A CSV import's current state.

Poll this until status is terminal. imported_rows climbs as the load runs, so it doubles as a progress bar against total_rows.

columns
ImportColumnMappingSchema · object[]
required

The mapping in force.

created_at
string<date-time>
required
error
string | null
required

Why the whole job failed, if it did.

failed_rows
integer
required

Rows that could not be written: the exact count.

id
string<uuid>
required
imported_rows
integer
required

Rows written so far.

row_errors
ImportRowErrorSchema · object[]
required

A capped sample of per-row failures; failed_rows carries the full count.

source_filename
string
required
status
enum<string>
required

Where a CSV import has got to.

PENDING is a parsed-and-stored upload the user has not committed yet: it holds an inferred mapping and nothing else. RUNNING means the table and its columns exist and the row job is inserting. The two terminal states are absorbing: a job never leaves them.

Available options:
pending,
running,
succeeded,
failed
table_id
string<uuid> | null
required

The table this created; null before commit.

total_rows
integer
required

Rows this import will write: the file's rows, capped by the plan and by whatever max_rows the commit asked for, or the rows its row_ranges hold.

updated_at
string<date-time>
required