Skip to content
Aurabase Logo
aurabase

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#

HeaderRequiredValue
apikeyyesProject API key (anon or service_role). X-API-Key is accepted too.
AuthorizationnoBearer <JWT>. Without it, the request runs as anon
Content-Typeyesapplication/json
Preferno`return=representation (default) \

Body parameters#

ParameterTypeRequiredDescription
tablestringyesName of the target table, in the path. Internal tables prefixed _aura_ are refused in 403.
values`object \object[]`yes
values.iduuid—Default: gen_random_uuid(). Omit for server generation.
values.created_attimestamptz—Default: now(). Omit for server timestamp.
values.[key]any—Any column declared by your schema.
on_conflictstringnoQuery 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.