# Create Policy Draft

`POST /policies` · Core · Policy & Approvals

Creates a new draft policy bundle for the project. The bundle is immediately editable and has no runtime effect until published. Requires `PROJECT_ADMIN`. The response includes the assigned `bundleId` (`bnd_<base62>`) which is the stable handle for all subsequent lifecycle operations on the bundle.

## 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 |
|---|---|---|---|
| `policy` | object | yes | The policy document. Every block is optional. A key other than these seven is refused with 422 `K9O_POLICY_BUNDLE_INVALID` and reason `unknown_surface`. |
| `policy.collections` | object | no | Row-level rules per collection, keyed by collection name. Each collection holds `actions`, keyed by `select`, `insert`, `update` or `delete`, and each action holds a `rule`: `true`, `false`, or a JSON predicate such as `{"eq": ["row.owner_id", "subject.id"]}`. An action with no rule is denied. Publishing compiles these rules into the database's row-level security. |
| _one of_ | | |  |
| _or_ | | |  |
| `policy.storage` | object | no | Storage rules per bucket, keyed by bucket name. They are checked on each storage request. |
| _one of_ | | |  |
| _or_ | | |  |
| `policy.tools` | object | no | Rules for tool calls, keyed by the tool's platform name or `*`. Each tool takes `invoke`. Each verb takes a rule list: a rule name from `rules`, an array of names, or a nested `{"all": [...]}` / `{"any": [...]}` expression of names. |
| _one of_ | | |  |
| _or_ | | |  |
| `policy.functions` | object | no | Rules for functions, keyed by function name, `<module>:*` or `*`. Each function takes `invoke`, and `actions` with `deploy`, `read` and `delete`. Each verb takes a rule list: a rule name from `rules`, an array of names, or a nested `{"all": [...]}` / `{"any": [...]}` expression of names. Only `invoke` is enforced; a rule on any other verb is refused with 422 `K9O_POLICY_BUNDLE_INVALID` and reason `not_enforced`. |
| _one of_ | | |  |
| _or_ | | |  |
| `policy.secrets` | object | no | Rules for secrets: `actions.create`, and per secret id (`sec_...`) or `*` a `reveal` verb. Each verb takes a rule list: a rule name from `rules`, an array of names, or a nested `{"all": [...]}` / `{"any": [...]}` expression of names. |
| _one of_ | | |  |
| _or_ | | |  |
| `policy.streams` | object | no | Rules for streams, keyed by stream name or `*`. Each stream takes `actions` with `create`, `read`, `delete`, `publish`, `subscribe` and `replay`. Each verb takes a rule list: a rule name from `rules`, an array of names, or a nested `{"all": [...]}` / `{"any": [...]}` expression of names. |
| _one of_ | | |  |
| _or_ | | |  |
| `policy.analytics` | object | no | Rules for analytics datasets, keyed by dataset slug or `*`. Each dataset takes `query`. Each verb takes a rule list: a rule name from `rules`, an array of names, or a nested `{"all": [...]}` / `{"any": [...]}` expression of names. |
| _one of_ | | |  |
| _or_ | | |  |
| `rules` | object | no | The named-rule catalogue, an array of rule objects that the unit surfaces refer to by name. Each rule has a `name` and a `when` predicate, plus either `action` (`allow` or `deny`) or `requires_approval_from` (an approver set). With `requires_approval_from` a rule may also set `recommendation`, `expires_after` (ISO 8601 duration), `escalation` (an array of `{escalate_after, to}`), `delegation_enabled` and `delegation_max_ttl`. `requires_proof` (`{max_age, min_tier}`) asks for a fresh step-up. Omit it or send null for no catalogue. |
| `editorMode` | enum ("visual", "json", "unspecified") | no | The editor the bundle was written in, so a console can reopen it in the same one: `visual`, `json`, or `unspecified`. |

```json
{
  "policy": {
    "collections": {},
    "storage": {}
  },
  "editorMode": "visual"
}
```

## Responses

- **201**: Created

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes | A policy bundle: the policy document, its named rules and where it is in its lifecycle. |
| `data.id` | string | yes | The bundle id (`pol_...`; bundles created before the rename keep a `bnd_...` id). |
| `data.projectId` | string | yes | The project the bundle belongs to (`proj_...`). |
| `data.status` | enum ("draft", "published", "superseded") | yes | `draft` can be edited, deleted and published. `published` is the bundle in force; a project has at most one. `superseded` was published and has been replaced or deactivated. |
| `data.policy` | object | yes | The policy document as stored: `collections`, `storage`, `tools`, `functions`, `secrets`, `streams` and `analytics`, each present only when it was sent. |
| `data.rules` | array of object | no | The named-rule catalogue. Present only when the bundle has one. |
| `data.createdBy` | string | yes | The id of the user who created the bundle (`usr_...`). |
| `data.createdAt` | string (date-time) | yes | When the bundle was created. |
| `data.publishedAt` | object | yes | When the bundle was published. Null for a draft. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.supersededAt` | object | yes | When the bundle stopped being in force. Null unless `status` is `superseded`. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.supersededBy` | object | yes | The id of the bundle that replaced this one. Null when nothing replaced it. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.source` | enum ("rest", "migration", "cli") | yes | How the bundle was created: `rest` through this API, `migration` by a platform migration, `cli` from the CLI. |
| `data.editorMode` | enum ("visual", "json", "unspecified") | yes | The editor the bundle was written in, so a console can reopen it in the same one: `visual`, `json`, or `unspecified`. |
| `data.supersededReason` | object | yes | The reason given when the bundle was deactivated. Null otherwise. |
| _one of_ | | |  |
| _or_ | | |  |
| `data.pendingChangeId` | object | yes | The id of a queued publish for this bundle that is waiting for an approver (`apr_...`). Set on the list and single-bundle reads; null when nothing is queued, and always null in create, update and current-policy responses. |
| _one of_ | | |  |
| _or_ | | |  |
| `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 role, which is required to create a policy bundle draft. |
| 403 | `K9O_POLICY_AUTHORING_AUTHORITY_INSUFFICIENT` | The caller's role is not authorised to author the approval rules declared in the submitted bundle for the targeted collection and operation scope. |
| 400 | `K9O_POLICY_NESTING_TOO_DEEP` | The policy rule in the submitted bundle exceeds the maximum nesting depth of 20; simplify the rule structure. |
| 400 | `K9O_POLICY_UNKNOWN_OPERATOR` | The submitted bundle contains a policy rule with an operator name not in the supported vocabulary. |
| 400 | `K9O_POLICY_UNKNOWN_CONTEXT_FIELD` | A subject or resource operand path in the submitted bundle does not match any known field for the target collection. |

## Code samples

### cURL

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

### fetch

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

### k9o CLI

```bash
k9o policy apply <file>
```

### @k9o/core

```typescript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.policies.create({
  policy: {
    collections: {},
    storage: {}
  },
  editorMode: 'visual'
})
```

### k9o

```python
# k9o = create_client(org_slug="playground", project_slug="storefront", api_key="k9o_…")
response = k9o.policies.create({
    "policy": {
        "collections": {},
        "storage": {}
    },
    "editorMode": "visual"
})
```

### sdk-go

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

### k9o

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

### dev.k9o:core

```java
// K9o k9o = K9o.createClient(K9o.Opts.builder().orgSlug("playground").projectSlug("storefront").apiKey("k9o_…").build());
var response = k9o.policies().create(Map.of("policy", Map.of("collections", Map.of(), "storage", Map.of()), "editorMode", "visual"))
```

### K9o.Core

```c#
// var k9o = K9oClient.Create(new K9oOptions { OrgSlug = "playground", ProjectSlug = "storefront", ApiKey = "k9o_…" });
var response = await k9o.Policies.CreateAsync(new Dictionary<string, object> { ["policy"] = new Dictionary<string, object> { ["collections"] = new Dictionary<string, object> {  }, ["storage"] = new Dictionary<string, object> {  } }, ["editorMode"] = "visual" })
```

### k9o

```ruby
# k9o = K9o.create_client(org_slug: "playground", project_slug: "storefront", api_key: "k9o_…")
response = k9o.policies.create({ policy: { collections: {  }, storage: {  } }, editorMode: "visual" })
```

### k9o/sdk

```php
// $k9o = K9oClient::create(['org_slug' => 'playground', 'project_slug' => 'storefront', 'api_key' => 'k9o_…']);
$response = $k9o->policies->create(['policy' => ['collections' => [], 'storage' => []], 'editorMode' => 'visual'])
```


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