Insert rows
/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 | Clé API du projet (anon ou service_role). X-API-Key accepté aussi. |
Authorization | no | Bearer <JWT utilisateur> — sans lui, la requête est traitée en anon |
Content-Type | yes | application/json |
Prefer | no | `return=representation (défaut) \ |
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
201CreatedInsertion successful. Body = { data, meta } by default.
200OKUpsert succeeded (?on_conflict= present).
204No ContentPrefer: return=minimal — no body, Preference-Applied header returned.
400Invalid Bad RequestBody, unknown column, or empty array. error.code = BAD_REQUEST or COLUMN_NOT_FOUND.
403ForbiddenRLS refuses write, or internal table _aura_*.
409ConflictSingle constraint violation without on_conflict. error.code = DUPLICATE_KEY.
413Payload Too LargeRequest body beyond MAX_BODY_SIZE (default 50 MB). There is no cap on the number of lines.
To know
The Prefer: return=representation header is added automatically by the SDK. Add Prefer: return=minimal to make the answer lighter.
Batch inserts are atomic: if one row violates a constraint, all are rolled back.
The Idempotency-Key header is not read on this route: two identical POSTs with the same key create two lines. To deduplicate, use ?on_conflict= and a unique constraint.