Skip to main content

Insert rows

Insert rows into a table, or update records that match existing unique values.

POST /projects/:projectid/databases/:dbid/tables/:tblid/rows

Authentication​

Send the project API key in the Authorization header, without a Bearer prefix. Requires databases.write for the database in the URL.

Request​

FieldTypeDescription
rowsarray of objects, requiredA non-empty array. Object keys are column names and values are the row data.

Every column name must follow the identifier rules. Send JSON booleans as true or false, not strings.

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 '{
"rows": [
{
"customer_name": "Ada",
"status": "active"
},
{
"customer_name": "Grace",
"status": "active"
}
]
}' \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/databases/${INTELLECTIBLE_DATABASE_ID}/tables/${INTELLECTIBLE_TABLE_ID}/rows"

Response​

201 Created

{
"rowIds": [
"row_id_1",
"row_id_2"
]
}

Columns and matching records​

Missing columns are added automatically, with types inferred from the supplied values. This behaviour is part of databases.write and does not require a separate databases.schema grant. Create columns explicitly first when you need a particular type, constraint, or vector dimension. Arrays are treated as vector data during inference, not automatically as JSON arrays.

If the supplied data includes a row ID or a recognised unique column, matching existing records can be updated instead of inserting new ones. When several matching columns are supplied, a match on any of them can qualify; they are not treated as a composite key. Avoid ambiguous matches and duplicate unique values within a batch.

The request uses the union of the supplied column names. A value missing from one row becomes null for that column, which can also affect matched updates. Do not treat this as a sparse patch operation; use Update a cell for a single value.

Returned IDs and retries​

rowIds contains IDs returned by the insert/update operation. Keep these for later cell updates or row deletion. In current row responses, the identifier field is intellectible_id.

Use manageable batches. Large requests can be split into multiple database operations, so a failure does not guarantee that no rows changed. Retrying a request without stable unique values can create duplicates; inspect the table before retrying an uncertain result.

See Errors and safe retries for shared failure handling.