Skip to main content
POST/data/{collection}

Insert Record

Inserts a new record into the named user-collection.

The platform auto-generates a rec_<base62> id if none is supplied.

Any caller-supplied metadata block is silently stripped before the INSERT reaches Postgres.

Passing ?requireApproval=true routes the write through the Maker-Checker evaluation engine.

If no auto-approve policy matches, the operation is queued as a pending change and the response returns HTTP 202 with meta.status: "pending_approval" instead of the committed record.

Errors:

  • K9O_COLLECTION_NOT_FOUND (404) if the collection does not exist.
  • K9O_CONSTRAINT_VIOLATION (409) for an id collision without an upsert flag.
Parameters
collection *path

The collection's name.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
Responses
HTTPK9O CodeDescription
200Success
201Created
202Accepted
401K9O_SESSION_EXPIREDYour session has expired; sign in again to insert records.
401K9O_INVALID_CREDENTIALSThe credentials provided are not valid; the insert request was rejected.
403K9O_ACCESS_DENIEDYour role does not permit inserting records into this collection.
403K9O_RESERVED_COLUMN_WRITE_PROHIBITEDThe request payload contains a reserved column name (prefixed with '_') that may only be written by the platform.
404K9O_COLLECTION_NOT_FOUNDThe target collection does not exist in this project.
409K9O_ALREADY_EXISTSThe record violates a unique constraint, for example a record with this id already exists in the collection.
409K9O_BYOK_REGION_MISMATCHThe record has an encrypted field for a data subject, and the project's customer-managed key does not cover the region the record is written in. Nothing was written, and the field is never sealed under a platform key.
422K9O_MALWARE_DETECTEDA file included in the request failed the malware scan and was not stored.
Response body (200)
data *object

The record as stored after the write, keyed by column name: every column of the collection's table, including id.

Protected columns come back as plaintext, except columns that need a reveal purpose, which come back in their opaque protected form.

With onConflict=ignore and an existing row, that existing row.

An anonymous guest-capture insert gets only { id }.

Values are serialised from their Postgres column type:

  • text, uuid and enum columns as strings
  • integer, real and double columns as numbers
  • bigint and numeric columns as strings (to keep precision)
  • boolean as true/false
  • timestamp and date columns as ISO 8601 date-time strings
  • json and jsonb as the stored JSON value
  • array columns as JSON arrays
  • bytea as {"type":"Buffer","data":[...bytes]}
  • a SQL NULL as null
meta *any

Request metadata: cost, timing, request and trace ids.

Response body (201)
data *object

The record as stored after the write, keyed by column name: every column of the collection's table, including id.

Protected columns come back as plaintext, except columns that need a reveal purpose, which come back in their opaque protected form.

With onConflict=ignore and an existing row, that existing row.

An anonymous guest-capture insert gets only { id }.

Values are serialised from their Postgres column type:

  • text, uuid and enum columns as strings
  • integer, real and double columns as numbers
  • bigint and numeric columns as strings (to keep precision)
  • boolean as true/false
  • timestamp and date columns as ISO 8601 date-time strings
  • json and jsonb as the stored JSON value
  • array columns as JSON arrays
  • bytea as {"type":"Buffer","data":[...bytes]}
  • a SQL NULL as null
meta *any

Request metadata: cost, timing, request and trace ids.

Response body (202)
data *object

The write was queued for approval (HTTP 202) because a bound approval policy requires it, or requireApproval=true was passed.

It expires after 28 days unless decided.

id *string

The pending change's id (apr_...).

Approve or reject it through the pending-approvals API.

status *"pending_approval"

Always pending_approval: nothing has been written.

The write runs when the change is approved.

collection *string

The collection the change targets.

operation *"insert" | "update" | "delete"

The write that was queued.

makerId *string

Who proposed the change: the accountable originator on a delegated call, otherwise the caller (a user id, or tok_... for a token).

proposedPayload *object

The request body as sent, applied when the change is approved: column name to value.

Empty for a delete.

targetRecordId *any

The record an update or delete targets; null for an insert.

One of: string
or: null
meta *object

Request metadata (cost, timing, request and trace ids), plus approval.

approval *object

Marks the answer as queued for approval.

status *"pending_approval"
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.from('products').insert({})

Showing example in TypeScript

Request example
Response example (200)
{}
Response example (201)
{}
Response example (202)
{
  "data": {
    "id": "string",
    "status": "pending_approval",
    "collection": "string",
    "operation": "insert",
    "makerId": "string",
    "targetRecordId": "string"
  },
  "meta": {
    "approval": {
      "status": "pending_approval"
    }
  }
}

More in Data, Queries & Vectors