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

Reject Change

Records a checker rejection decision on a pending change, capturing an optional reason in status_reason.

Errors:

  • K9O_APPROVAL_NOT_PENDING (409) for a decision on a change not in pending_approval status
  • K9O_APPROVAL_CANCELLED_BY_MAKER (409) for a decision on a maker-cancelled row
  • K9O_APPROVAL_NOT_AUTHORIZED (403) if the caller is not in the change's denormalized approver_set and holds no active approval delegation
  • K9O_APPROVAL_EXPIRED (410) when acting on an expired change

On rejection the pending-change status transitions to rejected and a data.write.approval.* audit event is emitted; the change is not committed.

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 reject pending changes in this project.
403K9O_RBAC_DENYA session is required to reject 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 in a state that permits rejection; it has already been decided, expired, or cancelled, or it was decided concurrently.
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.reject('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