Skip to main content
POST/approval-policies

Create Approval Policy

Creates a new draft policy bundle for the project, assigned a stable bundleId (bnd_<base62>).

The bundle is initialized in draft status with no runtime effect.

It can be edited via PATCH and then atomically activated via the publish endpoint.

These validation checks fire at draft creation time:

  • K9O_POLICY_NESTING_TOO_DEEP (400) if nesting depth exceeds 20.
  • K9O_POLICY_UNKNOWN_OPERATOR (400) for unknown operators.
  • K9O_POLICY_UNKNOWN_CONTEXT_FIELD (400) for unknown context fields.

K9O_POLICY_BUNDLE_INVALID (422) is returned when a bundle passes creation-time validation but later fails at publish time (e.g., schema drifted between draft and publish).

Requires PROJECT_ADMIN.

Parameters
projectSlug *path

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

It is unique within the org.

Request body
collection *string

The collection whose writes the policy applies to: a letter or underscore, then up to 62 letters, digits or underscores.

operation *"insert" | "update" | "delete"

The kind of write the policy applies to.

predicate *object

The condition, as a JSON predicate: {"<operator>": [arg, ...]}, nested as deep as you need.

Operators: eq, neq, gt, gte, lt, lte, in, contains, and, or, not.

A string that starts with maker. or change. reads a value from the write being checked:

  • maker.id, maker.account_type, maker.roles, maker.groups
  • change.table, change.operation, change.row.<field>, change.fields_modified, change.magnitude

Any other value is a literal.

A predicate with an operator or shape the platform can't evaluate is refused with 400 K9O_INVALID_FIELD_VALUE, and context.defects lists every problem.

action *"auto_approve" | "queue"

auto_approve applies a matching write with no checker; queue holds it for a checker.

In a strict-governance project, creating an auto_approve policy takes a project admin who is a person, plus a fresh step-up.

Responses
HTTPK9O CodeDescription
201Created
400K9O_POLICY_NESTING_TOO_DEEPThe approval policy rule exceeds the maximum nesting depth of 20.
400K9O_POLICY_UNKNOWN_OPERATORThe approval policy contains a rule with an operator name not in the supported vocabulary.
400K9O_POLICY_UNKNOWN_CONTEXT_FIELDA subject or resource operand path in the approval policy does not resolve to a known field.
401K9O_SESSION_EXPIREDThe caller's session token is expired or invalid; re-authenticate to continue.
403K9O_ACCESS_DENIEDThe caller does not hold PROJECT_ADMIN or PROJECT_AUTHOR role, which is required to author an approval policy.
403K9O_POLICY_AUTHORING_AUTHORITY_INSUFFICIENTThe caller's role is not authorised under the org-policy constraint to author an approval rule for the targeted collection and operation scope.
422K9O_POLICY_BUNDLE_INVALIDThe approval policy declaration is structurally well-formed but fails domain-level validation at apply time.
Response body (201)
data *object

An approval policy: which writes to a collection it matches, and whether a match is applied or held for a checker.

id *string

The policy id (apo_...).

collection *string

The collection whose writes the policy applies to.

operation *"insert" | "update" | "delete"

The kind of write the policy applies to.

predicate *object

The condition, as a JSON predicate: {"<operator>": [arg, ...]}, nested as deep as you need.

Operators: eq, neq, gt, gte, lt, lte, in, contains, and, or, not.

A string that starts with maker. or change. reads a value from the write being checked:

  • maker.id, maker.account_type, maker.roles, maker.groups
  • change.table, change.operation, change.row.<field>, change.fields_modified, change.magnitude

Any other value is a literal.

action *"auto_approve" | "queue"

What happens to a matching write: auto_approve applies it with no checker, queue holds it for a checker.

Policies for the same collection and operation are tried oldest first, and the first whose predicate matches decides.

authoredBy *string

The id of the user who created the policy (usr_...).

createdAt *string <date-time>

When the policy was created.

meta *any
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.approvalPolicies.create({})

Showing example in TypeScript

Request example
{
  "collection": "string",
  "operation": "insert",
  "action": "auto_approve"
}
Response example (201)
{
  "data": {
    "id": "string",
    "collection": "string",
    "operation": "insert",
    "action": "auto_approve",
    "authoredBy": "string",
    "createdAt": "string"
  }
}

More in Policy & Approvals