Skip to main content
GET/pending-approvals

List Pending Approvals

Returns the caller's approver inbox: a cursor-paginated list of pending-change envelopes (pch_<base62>) where the caller is a member of the denormalized approver_set or holds an active approval delegation.

Supports filtering by status, collection, and maker.

The auth floor is approver_set membership or an active delegation row expanding the caller into an approver set.

Parameters
projectSlug *path

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

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FIELD_VALUElimit is not an integer between 1 and 200, or status is not one of pending_approval, approved, rejected, expired, redeemed.
400K9O_INVALID_CURSORThe cursor is malformed, or was issued for a different project, status filter or queue scope; omit it to start from the newest pending change.
401K9O_SESSION_EXPIREDThe caller's session token is expired or invalid; re-authenticate to continue.
403K9O_ACCESS_DENIEDThe caller does not hold the minimum required role to view the pending-approvals inbox for this project.
Response body (200)
data *object[]

Pending changes, newest first.

A project admin or auditor sees the whole queue; anyone else sees only the changes they proposed.

When more match, meta.cursor.next holds the cursor for the next page; otherwise it is null.

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.list()

Showing example in TypeScript

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