Skip to main content
DELETE/data/{collection}/{id}

Delete Record

Permanently deletes the record identified by id from the named collection, returning {id} on success.

Passing ?requireApproval=true routes the delete through the Maker-Checker evaluation engine: if no auto-approve policy matches, the deletion is queued as a pending change and the response returns HTTP 202 with meta.status: "pending_approval" instead of executing immediately.

Returns K9O_COLLECTION_NOT_FOUND (404) if the collection does not exist and K9O_NOT_FOUND (404) if the record id does not exist.

Parameters
collection *path

The collection's name.

id *path

The record's id: the value of its id column, up to 256 characters.

projectSlug *path

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

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
202Accepted
401K9O_SESSION_EXPIREDYour session has expired; sign in again to delete records.
401K9O_INVALID_CREDENTIALSThe credentials provided are not valid; the delete request was rejected.
403K9O_ACCESS_DENIEDYour role does not permit deleting records from this collection.
404K9O_COLLECTION_NOT_FOUNDThe target collection does not exist in this project.
409K9O_STATE_CONFLICTThe record has live dependent rows referencing it through a foreign key that is not ON DELETE CASCADE; remove the dependants or declare the foreign key ON DELETE CASCADE.
Response body (200)
data *object

The record was soft-deleted: hidden from reads and purged after the collection's retention window; restorable until then.

id *string

The deleted record's id, as given in the path.

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').delete().eq('id', 'prod_demo00000001')

Showing example in TypeScript

Response example (200)
{
  "data": {
    "id": "string"
  }
}
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