Skip to main content
POST/pending-approvals/{pendingId}/approve

Approve Change

Records a checker approval decision on a pending change.

The change must be in pending_approval status.

Errors:

  • Any other non-pending state returns K9O_APPROVAL_NOT_PENDING (409).
  • A maker-cancelled row returns K9O_APPROVAL_CANCELLED_BY_MAKER (409).
  • A caller who is not in the change's denormalized approver_set and holds no active approval delegation gets K9O_APPROVAL_NOT_AUTHORIZED (403).

On success, if the approver-set threshold is satisfied, the platform atomically commits the pending change and emits a data.write.approval.* audit event.

Subscription events fire on commit, not on the approval action itself.

Parameters
pendingId *path

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

projectSlug *path

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

It is unique within the org.

Request body
reasonany

Why you decided this way.

Surrounding whitespace is trimmed, and an empty string counts as no reason.

Required to reject.

One of: string
or: null
reviewBasis"read" | "verified" | "unread"

What you went on.

Required to approve a held function call or MCP tool call, and ignored for other changes. read: you read the held payload (only when the case holds one). verified: you checked it another way. unread: you approved without seeing it.

Responses
HTTPK9O CodeDescription
200Success
401K9O_SESSION_EXPIREDThe caller's session token is expired or invalid; re-authenticate to continue.
403K9O_IAM_POLICY_DENIEDThe caller's bound IAMPolicy ceiling denies approvals:manage, so they are not authorised to decide pending changes in this project.
403K9O_RBAC_DENYA session is required to approve a pending change: a personal access token alone is refused with `context.reason` `session_required`, and a service, workload or extension token with `human_only`.
404K9O_POLICY_NOT_FOUNDNo pending-approval record with the supplied identifier exists or is accessible in this project.
409K9O_STATE_CONFLICTThe pending change is not awaiting a decision; it has already been approved, rejected, cancelled, or has expired (including a lapsed TTL), or it was decided concurrently.
409K9O_APPROVAL_STALE_BASEThe pending change was based on a committed-state version that has since been superseded; it was auto-rejected due to a conflicting write.
409K9O_BYOK_REGION_MISMATCHApplying the approved change writes an encrypted field for a data subject, and the project's customer-managed key does not cover the region it is written in. The change was not applied, and the field is never sealed under a platform key.
Response body (200)
data *object

A pending change: a write or action held until an approver decides it.

id *string

The pending change id (apr_...).

status *"pending_approval" | "approved" | "redeemed" | "rejected" | "expired" | "cancelled" | "superseded"

Where the change stands. pending_approval is waiting for a decision, including a change that has some but not all of the approvals it needs. approved was granted; redeemed was granted and then carried out by its maker. rejected, expired, cancelled and superseded are closed without being applied.

collection *any

The collection the change writes to. _policies for a policy publish.

Null for a change that is not a data write, such as a function call or a platform action.

One of: string
or: null
operation *any

The kind of write: insert, update or delete for a single record.

Null for a change that is not a data write.

One of: string
or: null
makerId *string

Who proposed the change: a user (usr_...), a token (tok_...) or another principal id.

proposedPayload *object

What the change would do.

For a data write it is the proposed record.

For any other change it holds that change's own details: a policy publish, for example, carries kind policy_publish and the bundleId.

targetRecordId *any

The id of the record (or policy bundle) the change targets.

Null for an insert and for a change with no single target.

One of: string
or: null
approverId *any

Who decided the change (usr_...).

Null while it is undecided.

One of: string
or: null
decidedAt *any

When the change was decided.

Null while it is undecided.

One of: string <date-time>
or: null
decisionReason *any

The reason the approver gave.

Null when none was given.

One of: string
or: null
createdAt *string <date-time>

When the change was proposed.

expiresAt *any

When the change expires if it is still undecided.

Null when it does not expire.

One of: string <date-time>
or: null
meta *any
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.approvals.approve('apr_3Lq9Wx2Km7Rp5Tz8', {})

Showing example in TypeScript

Request example
{
  "reason": "string",
  "reviewBasis": "read"
}
Response example (200)
{
  "data": {
    "id": "string",
    "status": "pending_approval",
    "collection": "string",
    "operation": "string",
    "makerId": "string",
    "targetRecordId": "string",
    "approverId": "string",
    "decidedAt": "string",
    "decisionReason": "string",
    "createdAt": "string",
    "expiresAt": "string"
  }
}

More in Policy & Approvals