# Create Approval Policy

`POST /approval-policies` · Core · Policy & Approvals

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

| Name | In | Required | Description |
|---|---|---|---|
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `collection` | string | yes | The collection whose writes the policy applies to: a letter or underscore, then up to 62 letters, digits or underscores. |
| `operation` | enum ("insert", "update", "delete") | yes | The kind of write the policy applies to. |
| `predicate` | object | yes | 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` | enum ("auto_approve", "queue") | yes | `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

- **201**: Created

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes | An approval policy: which writes to a collection it matches, and whether a match is applied or held for a checker. |
| `data.id` | string | yes | The policy id (`apo_...`). |
| `data.collection` | string | yes | The collection whose writes the policy applies to. |
| `data.operation` | enum ("insert", "update", "delete") | yes | The kind of write the policy applies to. |
| `data.predicate` | object | yes | 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. |
| `data.action` | enum ("auto_approve", "queue") | yes | 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. |
| `data.authoredBy` | string | yes | The id of the user who created the policy (`usr_...`). |
| `data.createdAt` | string (date-time) | yes | When the policy was created. |
| `meta` | object | yes |  |


## Errors

| HTTP | Code | When |
|---|---|---|
| 401 | `K9O_SESSION_EXPIRED` | The caller's session token is expired or invalid; re-authenticate to continue. |
| 403 | `K9O_ACCESS_DENIED` | The caller does not hold PROJECT_ADMIN or PROJECT_AUTHOR role, which is required to author an approval policy. |
| 403 | `K9O_POLICY_AUTHORING_AUTHORITY_INSUFFICIENT` | The caller's role is not authorised under the org-policy constraint to author an approval rule for the targeted collection and operation scope. |
| 400 | `K9O_POLICY_NESTING_TOO_DEEP` | The approval policy rule exceeds the maximum nesting depth of 20. |
| 400 | `K9O_POLICY_UNKNOWN_OPERATOR` | The approval policy contains a rule with an operator name not in the supported vocabulary. |
| 400 | `K9O_POLICY_UNKNOWN_CONTEXT_FIELD` | A subject or resource operand path in the approval policy does not resolve to a known field. |
| 422 | `K9O_POLICY_BUNDLE_INVALID` | The approval policy declaration is structurally well-formed but fails domain-level validation at apply time. |

## Code samples

### cURL

```bash
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/approval-policies' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/approval-policies', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({}),
});
const { data, meta } = await res.json();
```

### k9o CLI

```bash
k9o approval-policy create --collection <name> --operation insert|update|delete --action queue|auto_approve --predicate '<json>'
```

### @k9o/core

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

### k9o

```python
# k9o = create_client(org_slug="playground", project_slug="storefront", api_key="k9o_…")
response = k9o.approval_policies.create({})
```

### sdk-go

```go
// ctx := context.Background()
// client, _ := k9o.NewClient(k9o.ClientOpts{OrgSlug: "playground", ProjectSlug: "storefront", APIKey: "k9o_…"})
data, _, kerr := client.ApprovalPolicies.Create(ctx, map[string]any{})
```

### k9o

```rust
// let k9o = Client::new(ClientOpts { org_slug: "playground".into(), project_slug: "storefront".into(), api_key: "k9o_…".into() })?;
let resp = k9o.approval_policies.create(json!({})).await?
```

### dev.k9o:core

```java
// K9o k9o = K9o.createClient(K9o.Opts.builder().orgSlug("playground").projectSlug("storefront").apiKey("k9o_…").build());
var response = k9o.approvalPolicies().create(Map.of())
```

### K9o.Core

```c#
// var k9o = K9oClient.Create(new K9oOptions { OrgSlug = "playground", ProjectSlug = "storefront", ApiKey = "k9o_…" });
var response = await k9o.ApprovalPolicies.CreateAsync(new Dictionary<string, object> {  })
```

### k9o

```ruby
# k9o = K9o.create_client(org_slug: "playground", project_slug: "storefront", api_key: "k9o_…")
response = k9o.approval_policies.create({  })
```

### k9o/sdk

```php
// $k9o = K9oClient::create(['org_slug' => 'playground', 'project_slug' => 'storefront', 'api_key' => 'k9o_…']);
$response = $k9o->approval_policies->create([])
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/create-approval-policy
