Insert rows
POST/v1/db/{project_id}/{table}
Inserts one or more records into a table in the project schema. Supports upsert via on_conflict and returns rows created by default.
Headers#
| Header | Required | Value |
|---|---|---|
apikey | yes | Project API key (anon or service_role). X-API-Key is accepted too. |
Authorization | no | Bearer <JWT>. Without it, the request runs as anon |
Content-Type | yes | application/json |
Prefer | no | `return=representation (default) \ |
Body parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
table | string | yes | Name of the target table, in the path. Internal tables prefixed _aura_ are refused in 403. |
values | `object \ | object[]` | yes |
values.id | uuid | — | Default: gen_random_uuid(). Omit for server generation. |
values.created_at | timestamptz | — | Default: now(). Omit for server timestamp. |
values.[key] | any | — | Any column declared by your schema. |
on_conflict | string | no | Query parameter (no body). Constraint column(s) for upsert: ?on_conflict=id. An upsert responds 200 OK, a simple insert 201 Created. |
Response codes#
201 Created— Insertion successful. Body = { data, meta } by default.200 OK— Upsert succeeded (?on_conflict= present).204 No Content— Prefer: return=minimal — no body, Preference-Applied header returned.400 Bad Request— Body, unknown column, or empty array. error.code = BAD_REQUEST or COLUMN_NOT_FOUND.403 Forbidden— RLS refuses write, or internal table _aura_*.409 Conflict— Single constraint violation without on_conflict. error.code = DUPLICATE_KEY.413 Payload Too Large— Request body beyond MAX_BODY_SIZE (default 50 MB). There is no cap on the number of lines.
To know#
Info
The Prefer: return=representation header is added automatically by the SDK. Add Prefer: return=minimal to make the answer lighter.
Attention
Batch inserts are atomic: if one row violates a constraint, all are rolled back.
Attention
The Idempotency-Key header is not read on this route: two identical POSTs with the same key create two rows. To deduplicate, use ?on_conflict= and a unique constraint.
Last updated · Apr 15, 2026↗ Edit on GitHub↗ Report a problem