/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.
| collection * | path | The collection's name. |
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | Success | |
| 201 | Created | |
| 202 | Accepted | |
| 401 | K9O_SESSION_EXPIRED | Your session has expired; sign in again to insert records. |
| 401 | K9O_INVALID_CREDENTIALS | The credentials provided are not valid; the insert request was rejected. |
| 403 | K9O_ACCESS_DENIED | Your role does not permit inserting records into this collection. |
| 403 | K9O_RESERVED_COLUMN_WRITE_PROHIBITED | The request payload contains a reserved column name (prefixed with '_') that may only be written by the platform. |
| 404 | K9O_COLLECTION_NOT_FOUND | The target collection does not exist in this project. |
| 409 | K9O_ALREADY_EXISTS | The record violates a unique constraint, for example a record with this id already exists in the collection. |
| 409 | K9O_BYOK_REGION_MISMATCH | The 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. |
| 422 | K9O_MALWARE_DETECTED | A file included in the request failed the malware scan and was not stored. |
| data * | object | The record as stored after the write, keyed by column name: every column of the collection's table, including Protected columns come back as plaintext, except columns that need a reveal purpose, which come back in their opaque protected form. With An anonymous guest-capture insert gets only Values are serialised from their Postgres column type:
|
| meta * | any | Request metadata: cost, timing, request and trace ids. |
| data * | object | The record as stored after the write, keyed by column name: every column of the collection's table, including Protected columns come back as plaintext, except columns that need a reveal purpose, which come back in their opaque protected form. With An anonymous guest-capture insert gets only Values are serialised from their Postgres column type:
|
| meta * | any | Request metadata: cost, timing, request and trace ids. |
| data * | object | The write was queued for approval (HTTP 202) because a bound approval policy requires it, or It expires after 28 days unless decided. |
| id * | string | The pending change's id ( Approve or reject it through the pending-approvals API. |
| status * | "pending_approval" | Always 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 |
| 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 * | object | Marks the answer as queued for approval. |
| status * | "pending_approval" | |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.from('products').insert({})Showing example in TypeScript
{}{}{
"data": {
"id": "string",
"status": "pending_approval",
"collection": "string",
"operation": "insert",
"makerId": "string",
"targetRecordId": "string"
},
"meta": {
"approval": {
"status": "pending_approval"
}
}
}